# 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

- [Full list of error codes](/docs/api/errors)
- [Retry safely with Idempotency-Key](/docs/getting-started/idempotency)
- [Rate limits and 429 responses](/docs/getting-started/rate-limits)

