Errors

Every error code the API returns, by status, with when it happens and what to do.

Error body

{
  "error": "insufficient_funds",
  "message": "Your wallet available is below this amount. Fund your wallet, then retry.",
  "request_id": "req_a1b2c3"
}

400 Bad request

Code	When
`invalid_request`	A required field is missing or malformed. The message names it.
`invalid_amount`	`amount` is missing, not a number, or not above zero.
`connection_not_found`	`connection_id` on a checkout names no connected connection on the account.
`site_required`	The account has no stored login for that merchant. Pass `start_url`, or connect the merchant once in the console.
`site_ambiguous`	The account has several logins for that merchant. `hosts` lists them; pass `start_url`.
`agent_required`	The account has several agents and none was named. Name one in the console.

401 Unauthorized

Code	When
`missing_api_key`	No `Authorization: Bearer` header.
`invalid_api_key`	The key is unknown or revoked.
`expired_api_key`	The key passed its expiry. `expired_at` says when.

402 Payment required

Code	When
`insufficient_funds`	The requested cap exceeds the wallet's `available`.
`plan_limit`	The plan's cards a month, or per-card cap, is reached. `limit` carries the figure.
`wallet_limit`	A top-up would take the wallet above its ceiling.
`funding_budget_reached`	The account's funding budget for the period is reached.
`funding_unavailable`	Top-ups are paused for the moment. Try later.
`funding_refused`	A fence refused the top-up for another reason; `code` carries it.

404 Not found

Code	When
`card_not_found`	No such card on the account. On `DELETE /v1/cards/{id}`: no such connected card (an issued card is closed, not removed). On a checkout with `own_card_id`: no such connected card.
`spend_not_found`	No such spend on the account.
`checkout_not_found`	No such checkout on the account, including a `resume_of` that is not yours.
`connection_not_found`	No such connection on the account.
`account_not_found`	The key's account could not be loaded.
`not_found`	No route for the method and path.

409 Conflict

Code	When
`agent_paused`	The person paused the agent in the console. Resume it there.
`busy`	The merchant session is running another checkout. Retry shortly with the same `idempotency_key`.
`not_resumable`	The `resume_of` run left nothing in the basket to continue from. Start again.

500 and 502 Upstream

Code	When
`server_error`	An unexpected failure. Quote the `request_id`.
`checkout_create_failed`	The run document could not be created.
`card_issue_failed`, `reveal_failed`, `close_failed`, `remove_failed`, `connect_failed`	A card step failed upstream; the message says which.
`spend_status_failed`, `wallet_read_failed`	A read failed upstream.
`checkout_start_failed`, `enqueue_failed`	The engine could not be started. On `enqueue_failed` the body carries the `checkout_id` that was created and marked `error`.
`connect_start_failed`, `disconnect_failed`	A connection step failed. Retry.
`funding_session_failed`, `bank_transfer_failed`	The top-up could not be opened or recorded.

503 Unavailable

Code	When
`own_card_unavailable`	Connecting a person's own card is not switched on for the account.
`unavailable`	The engine refused the run for the moment. Try again shortly.