Errors

Success and failure use one envelope.

{ "ok": true, "description": "Checkout created", "data": { } }

{ "ok": false, "description": "Missing, unknown or revoked API key", "data": {}, "code": 2781 }

Field	Meaning
ok	true on success. false on error
description	Text for logs and for people. Do not branch on it
data	Payload on success. {} on error
code	Errors only. Branch on this number

Branch on the HTTP status, then on code.

HTTP status

HTTP	Meaning	Action
200	Success, or a replayed create	Use data
201	Checkout created	Use data
400	Invalid request	Fix the request. Do not retry the same body
401	Key missing, unknown, or revoked	Fix the key. Do not retry
404	No checkout for your key	Check the id
409	Wallet not ready, on create	See the code
422	Amount or rail refused	Fix the amount, or wait until collection is on
429	Over the rate limit	Wait, then retry
503	A dependency is down	Retry with the same Idempotency-Key

Merchant API codes

Code	HTTP	Meaning
1701	400	Invalid body or headers, or a bad return_url. description says return_url is not a URL or return_url must be https
1804	429	More than 120 requests in one minute
2781	401	Missing, unknown, or revoked API key
2782	503	The key service did not answer
2783	404	Checkout not found, including another merchant's id
2702	422	Amount outside the rail limits, or not a whole unit where the rail requires it
2721	422	Collection is off on this deployment
2709	409	The wallet is not provisioned. Finish account setup in the hub
2752	503	The ledger did not answer the wallet check. Retry

A refused create does not open a checkout. If a create times out, retry with the same Idempotency-Key. You get the checkout that exists, or a new one.

Payer-page codes

These come from the hosted page, not from your server calls.

Code	HTTP	Meaning
2784	409	Checkout expired
2785	409	Checkout already paid
2786	409	A card payment is already in progress

Card setup on that page can also return 2771 to 2777. Your confirm call is still GET /checkouts/:id.

Retry

Result	Action
503 or a network error	Retry the same body and the same Idempotency-Key
429	Wait, then retry. The same key is valid
400, 401, 404, 409, 422	Change the request. The same request fails again