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:
curl -sS "$BUSINESS_API/customers?after=not-a-cursor" \
-H "Authorization: Bearer $API_KEY"
{
"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:
{
"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#
- Branch on
error_code. When your client does not know it, fall back tocode, which maps to a default for each case (INVALID_REQUESTtorequest.invalid,UNAUTHORIZEDtoauth.unauthenticated,NOT_FOUNDtoresource.not_found). - Never match on
detail: its wording can change without notice. - Retry only the problems marked as temporary:
RATE_LIMITED(429),INTEGRATION_UNAVAILABLE(503),DEADLINE_EXCEEDED(504) andINTERNAL_ERROR(500). On aPOST, retry with the sameIdempotency-Key. Any other4xxfails again until the request changes. - Log the
request_id. You can also send your own identifier in aRequest-Id(orX-Request-Id) header, up to 128 visible ASCII characters; the server echoes it in the response and its logs. Without one, the server generatesreq_followed by 32 hexadecimal characters.