Errors

Errors return a non-2xx status and a JSON body with a human-readable error and a stable machine-readable code:

{
  "error": "A card holder with external ID \"S1024\" already exists.",
  "code": "conflict"
}

Branch on code, not on the message text, which may be reworded.

Codes

Status	code	Meaning	What to do
400	bad_request	Body is not valid JSON, a required parameter is missing, or there is nothing to update	Fix the request
401	unauthorized	Missing, malformed, wrong, revoked or expired key	Check the key
403	forbidden	The key lacks a required scope	Add the scope or use another key
404	not_found	No such record in your organisation	Check the ID
409	conflict	Duplicate external ID, an invalid status transition, or an operation already in flight	Resolve the conflict; for an in-flight idempotent request retry shortly
412	precondition_failed	A prerequisite is missing, for example no approved photo or no card template	Satisfy the prerequisite
413	quota_exceeded	The organisation has reached its photo storage limit	Free space or raise the quota
422	validation_failed	A field failed validation; error names the first problem	Fix the field
429	rate_limited	Too many requests	Wait Retry-After seconds
500	internal	Something went wrong on our side	Retry with backoff; contact support if it persists

Retrying

Retry 429 after the Retry-After interval, and 500 or network failures with exponential backoff. Do not retry 4xx responses other than 429 and 409 on an in-flight idempotent request, because the same request will fail the same way.