Errors

One envelope everywhere: a sentence, a code, a request id.

{
  "error": "The request body has problems.",
  "code": "VALIDATION_FAILED",
  "requestId": "a36bda957b8a7631-YVR",
  "docs_url": "https://docs.taxpio.com/errors#validation-failed",
  "problems": [{ "field": "inputs.taxableTotalProfitsPence", "message": "taxableTotalProfitsPence must be a whole number of at least 0." }]
}

Branch on code, show error to a person, log requestId. Validation failures list every problem with the field that carries it. A code the route names is kept; otherwise the code is the one for the status.

Code	Status	Meaning
`BAD_REQUEST`	400	As the status says.
`UNAUTHENTICATED`	401	As the status says.
`PAYMENT_REQUIRED`	402	As the status says.
`FORBIDDEN`	403	As the status says.
`NOT_FOUND`	404	No such resource in this environment.
`METHOD_NOT_ALLOWED`	405	As the status says.
`NOT_ACCEPTABLE`	406	As the status says.
`REQUEST_TIMEOUT`	408	As the status says.
`CONFLICT`	409	The request conflicts with the current state (the message says how).
`GONE`	410	As the status says.
`PAYLOAD_TOO_LARGE`	413	The body exceeds the limit.
`UNSUPPORTED_MEDIA_TYPE`	415	Send application/json.
`VALIDATION_FAILED`	422	One or more fields are wrong; problems lists them.
`LOCKED`	423	As the status says.
`PRECONDITION_REQUIRED`	428	As the status says.
`RATE_LIMITED`	429	Over the per-minute limit; retry-after says when.
`INTERNAL`	500	Something failed on our side; quote the request id.
`NOT_IMPLEMENTED`	501	As the status says.
`UNAVAILABLE`	503	As the status says.
`TIMEOUT`	504	As the status says.
`ORIGIN_REQUIRED`	403	A browser mutation from another origin (product routes only).
`PASSKEY_REQUIRED`	403	As the status says.
`PASSKEY_ENROLLMENT_REQUIRED`	428	As the status says.
`RECENT_MFA_REQUIRED`	428	As the status says.
`RECENT_AUTHENTICATION_REQUIRED`	403	As the status says.
`ACCOUNT_PASSWORD_REQUIRED`	428	As the status says.
`EMAIL_VERIFICATION_REQUIRED`	403	As the status says.
`VERIFICATION_DELIVERY_FAILED`	503	As the status says.
`RESOURCE_ROUTE_UNAVAILABLE`	503	As the status says.
`MALWARE_DETECTED`	422	As the status says.
`NONDETERMINISTIC_PROVIDER_RETRY`	503	As the status says.
`CREDITS_REQUIRED`	402	A live operation needs more credits than the workspace holds.
`API_KEY_MISSING`	401	No bearer token was sent.
`API_KEY_INVALID`	401	The token is not a key TaxPio issued.
`API_KEY_REVOKED`	401	The key was revoked; mint a new one.
`API_KEY_EXPIRED`	401	The key passed its expiry.
`WORKSPACE_SUSPENDED`	403	The workspace is not active.
`APPLICATION_ARCHIVED`	403	The application was archived; its keys no longer act.
`SCOPE_REQUIRED`	403	The key lacks the scope the operation needs (required_scope says which).
`PRODUCTION_REVIEW_REQUIRED`	403	A live key was used before production review approved the workspace.
`IDEMPOTENCY_KEY_INVALID`	400	Idempotency-Key is not 8 to 128 characters of letters, digits, _ - . :.
`IDEMPOTENCY_KEY_REUSED`	409	The same key was sent with a different body.
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	The first request with this key is still running.
`BODY_INVALID`	400	The body is not valid JSON.
`UNSUPPORTED_PROGRAM`	422	The jurisdiction, program or tax year is not offered (the message says what is).
`SANDBOX_ONLY`	403	Sandbox tooling was called with a live key.
`CONNECTION_PENDING`	409	As the status says.
`CONNECTION_REVOKED`	409	As the status says.
`CONNECTION_PERMISSION_REQUIRED`	403	As the status says.
`LIVE_ONLY`	403	A government-facing operation was called with a sandbox key.
`WEBHOOK_SIGNATURE_INVALID`	401	The sink could not verify the delivery's signature.