Errors

Errors are RFC 9457(opens in a new tab) problem documents (Content-Type: application/problem+json):

{
  "type": "about:blank",
  "title": "Invalid request",
  "status": 400,
  "detail": "unknown country",
  "code": "unknown_country",
  "request_id": "01a166eb2f3a76c8b7c8a8c37d21aae3"
}

code is stable and meant for programs. Branch on it, not on detail, whose wording may change.
request_id is also sent in the X-Request-Id header. Quote it when you contact support. You may send your own X-Request-Id (8 to 64 characters of letters, digits, ., _ or -) to correlate logs.
Input that does not match the schema is 400 with code invalid_request and an errors list: a JSON pointer to each field, a code and a message.

Statuses

Status	Meaning	Retry?
400	The request is not valid (`code` says why)	After fixing it
401	No credential, or not a valid one	After fixing it
403	Valid credential, not allowed (`code` may say why, e.g. `no_org_read`)	No
404	Not found, or not yours (the API does not tell the two apart)	No
409	Conflicts with the current state (`code` says which)	After reading the state again
413	Body too large	No
429	Rate limit or daily quota (`rate_limited`, `quota_exceeded`)	After `Retry-After`
5xx	Our fault, or a partner's (`503` with a `code` such as `escrow_unavailable`)	With backoff

Codes you will meet often: invalid_request, unauthorized, forbidden, not_found, rate_limited, quota_exceeded, personal_data (a text contained a phone number, e-mail address or identity number), unknown_country, webhook_url_refused, unknown_event_types, too_many_webhooks, rotation_pending, webhook_disabled. The OpenAPI document lists every code an operation can return.