Errors - Bouclay

Every error has the same shape, so one handler covers them all:

{
  "error": {
    "type": "request_error",
    "code": "invalid_field",
    "detail": "Request does not pass validation.",
    "errors": [
      { "field": "email", "message": "The email field is required." }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

code is stable. Branch on it in your code.
detail is a sentence for people. It may change, so don’t match on it.
errors lists each field that failed, on a 422.

Status codes

Status	Means	What to do
`400`	The request was malformed, for example `invalid_cursor`.	Fix the request.
`401`	`authentication_failed`: the key is missing, wrong or revoked.	Check the key.
`402`	`insufficient_credit`: a credit hold the credit can’t cover.	Stop the request. See Credit holds.
`403`	`permission_denied`: a restricted key without the scope.	Add the scope named in `detail`.
`404`	`not_found`: no such object, or an early access feature not yet on for your account.	Check the id.
`409`	A conflict, such as `idempotency_conflict`, `subscription_suspended` or `spending_cap_reached`.	Read `code`; the object is in a state that refuses this.
`410`	An expired link, such as a portal session.	Make a new one.
`422`	`invalid_field` or a business rule, such as `meter_billed_elsewhere`.	Fix the fields listed in `errors`.
`429`	`rate_limited`.	Wait for `Retry-After` seconds, then retry.
`5xx`	Something went wrong on our side.	Retry with the same `Idempotency-Key`.

Retrying safely

Retry 429 and 5xx responses, and network errors, with the same Idempotency-Key and a growing wait between tries. Bouclay replays the first answer if the request already went through, so a retry never does the work twice. Don’t retry 4xx errors other than 429 without changing the request: they will fail the same way.