Documentation

Errors

One error shape, stable codes, and what to do about each of them.

Error shape

Every error uses the same JSON shape, with a stable machine-readable code and a human-readable message:

HTTP/1.1 409 Conflict
{
  "error": {
    "code": "idempotency_mismatch",
    "message": "This Idempotency-Key was already used with a different request body.",
    "details": { "idempotency_key": "order-1042-attempt-1" }
  }
}

Branch on code, never on message — messages may be reworded; codes will not change within an API version.

Codes

Code	HTTP	Meaning	What to do
invalid_request	400	A parameter is missing, malformed or not allowed.	Fix the request; details lists the offending fields.
authentication_required	401	No API key, or the key is invalid or revoked.	Send a valid Bearer key.
step_up_required	401	A sensitive dashboard action needs recent re-authentication.	Re-authenticate, then retry.
insufficient_funds	402	The available balance cannot cover a payout or refund.	Wait for funds to become available.
card_declined	402	The issuer declined the card.	Ask the customer for another payment method. Do not retry automatically.
permission_denied	403	The key or user lacks the scope for this action.	Use a key with the required scope.
live_mode_disabled	403	Live processing is not enabled.	Use the sandbox. Live is not available yet.
verification_required	403	Business or bank verification must complete first.	Complete the requirements shown in the dashboard.
not_found	404	The object does not exist or belongs to another account.	Check the ID and the key's mode.
conflict	409	The request conflicts with the current state or a concurrent request.	Re-read the object and retry if still relevant.
idempotency_mismatch	409	The Idempotency-Key was reused with a different body.	Use a new key for a different request.
invalid_state	409	The transition is not allowed from the object's current state.	Check the object's status first.
payout_hold	423	Payouts are held, e.g. a new bank account is in its security hold.	Wait for the hold to end or contact support.
rate_limited	429	Too many requests.	Back off and retry after the Retry-After header.
internal_error	500	Something failed on our side.	Retry with the same Idempotency-Key.
provider_error	502	The payment provider returned an error or is unavailable.	Retry later with the same Idempotency-Key; the outcome is never guessed.

Retrying safely

Retry 429, 500 and 502 with exponential backoff and the same Idempotency-Key.
Never automatically retry card_declined: the issuer has decided.
On a timeout, retry with the same key — VEYRA returns the original outcome if the first attempt completed.