Errors

The application/problem+json shape of error responses, how code differs from error_code, validation params, Request-Id, and which errors are worth retrying.

Every 4xx or 5xx response from the API has Content-Type: application/problem+json and follows RFC 9457. The body reports the failure three ways: a broad code per kind of problem (code), a stable, specific code to translate and branch on (error_code), and fallback English text (detail). The OAuth endpoints under /oauth/ are the exception: they answer in the OAuth shape, with error and, sometimes, error_description.

Example request and response#

An invalid pagination cursor is refused before anything is read:

bash
curl -sS "$BUSINESS_API/customers?after=not-a-cursor" \
  -H "Authorization: Bearer $API_KEY"
json
{
  "type": "about:blank",
  "title": "Invalid Request",
  "status": 400,
  "detail": "invalid pagination cursor",
  "instance": "$BUSINESS_API/customers",
  "code": "INVALID_REQUEST",
  "error_code": "request.cursor_invalid",
  "request_id": "req_4e8a1c7f3b9d42e6a0c5f8b2d7e1a693"
}

Fields#

Field Content
type A link to the error's explanation, /docs/api/errors#<error_code> on the site's origin, when the operator has configured it. Otherwise about:blank.
title Short name of the broad problem, such as Invalid Request or Unauthorized.
status The response's HTTP status, repeated.
detail English text for whoever reads the logs. When the text would reveal the database or the server's internal code, the server replaces it with a generic sentence for the status, and a 500 always carries a generic sentence.
instance The request path.
code The broad problem in upper case: INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED and others.
error_code The specific code, lower case and dotted, such as validation.too_long or invoice.not_open. A shipped code is never renamed.
params Values for building the message, such as field, min and max. Present only when the error has them.
request_id The request's identifier, equal to the Request-Id header.
invalid_params Refused fields, each with name, reason and, when known, code.

Validation errors#

Creating an API key with a name longer than 128 characters returns the bounds in params, ready for a translated message:

json
{
  "type": "about:blank",
  "title": "Invalid Request",
  "status": 400,
  "detail": "name is required and at most 128 characters",
  "instance": "$BUSINESS_API/developer/api-keys",
  "code": "INVALID_REQUEST",
  "error_code": "validation.length_out_of_range",
  "params": { "field": "name", "min": "1", "max": "128" },
  "request_id": "req_7b2d9f4a1e6c40b8a3d5e9c2f1a8b046"
}

Handling an error#

  1. Branch on error_code. When your client does not know it, fall back to code, which maps to a default for each case (INVALID_REQUEST to request.invalid, UNAUTHORIZED to auth.unauthenticated, NOT_FOUND to resource.not_found).
  2. Never match on detail: its wording can change without notice.
  3. Retry only the problems marked as temporary: RATE_LIMITED (429), INTEGRATION_UNAVAILABLE (503), DEADLINE_EXCEEDED (504) and INTERNAL_ERROR (500). On a POST, retry with the same Idempotency-Key. Any other 4xx fails again until the request changes.
  4. Log the request_id. You can also send your own identifier in a Request-Id (or X-Request-Id) header, up to 128 visible ASCII characters; the server echoes it in the response and its logs. Without one, the server generates req_ followed by 32 hexadecimal characters.

Next steps#