Error codes

Errors use standard HTTP status codes and always return the same JSON shape, with a stable machine-readable code.

{
  "error": {
    "code": "validation_error",
    "message": "The request parameters are invalid.",
    "details": { "fields": { "amount": ["The amount must be greater than zero."] } },
    "request_id": "9f2c1c1e-..."
  }
}

Write your logic against code, not message. Messages may change, codes will not. details is only present when there is extra information.

Retry or not?

• 4xx: fix the request first. Retrying the same request will fail the same way. The exceptions are 409 request_in_progress and 429, which you can retry after a short wait.
• 5xx: safe to retry with the same Idempotency-Key. Failed requests are not stored, so the retry runs again without creating a duplicate.

All error codes