Error codes

Every error code the API returns, its HTTP status and type, and every payment decline code.

Errors use HTTP status codes and one body shape. Branch on type and code; never parse message. See Errors for how to handle them.

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "amount must be a positive integer (USDC atoms)",
    "param": "amount",
    "request_id": "6f1c2a9e-3b7d-4c55-9a0e-2d4b8f1e7c30"
  }
}

The error object

typestring: One of: invalid_request_error, authentication_error, permission_error, idempotency_error, rate_limit_error, api_error
codestring: Stable, machine-readable code (see the error code catalogue).
messagestring: Human-readable explanation. May change; do not parse it.
paramstring: The parameter (or header) at fault.
request_idstring: The Request-Id of the request; quote it to support.

`permission_error`

Code	HTTP	Meaning
`account_disabled`	`403`	The merchant account is disabled. Read-only requests still work. Contact ZyloPay support.
`account_restricted`	`403`	An account involved in this action cannot be used with ZyloPay right now. Nothing was done. Contact ZyloPay support.
`insufficient_scope`	`403`	The API key lacks the scope this endpoint requires (see `required_scope` in the message).
`ip_not_allowed`	`403`	The request IP is not in the API key's IP allowlist.
`kyb_required`	`403`	Live mode needs an approved business verification (KYB) for this action.
`publishable_key_not_allowed`	`403`	Publishable keys cannot call this endpoint; use a secret key from your server.

`invalid_request_error`

Code	HTTP	Meaning
`account_not_live`	`409`	The merchant is not registered on this network yet (go live from the dashboard first).
`amount_too_large`	`400`	The amount exceeds what is allowed (for a refund: the amount still refundable).
`api_version_invalid`	`400`	The `ZyloPay-Version` header names a version that does not exist.
`cursor_invalid`	`400`	The pagination cursor is malformed or belongs to another list.
`network_mismatch`	`400`	An `X-Network` header was sent that contradicts the API key's mode. API keys choose the network; omit the header.
`parameter_invalid`	`400`	A parameter has an invalid value (see `param`).
`parameter_missing`	`400`	A required parameter is missing (see `param`).
`parameter_unknown`	`400`	The request contains a parameter the endpoint does not accept (see `param`).
`payment_already_refunded`	`409`	The payment has already been fully refunded.
`payment_intent_unexpected_state`	`409`	The payment intent is not in a state that allows this action (see `message`).
`refund_daily_limit_reached`	`409`	The account's daily refund limit would be exceeded.
`refund_in_progress`	`409`	Another refund of this payment is being sent; retry after it completes.
`refund_window_expired`	`409`	The payment is older than the refund window of the account.
`resource_missing`	`404`	No such object for this account and mode.
`terminal_inactive`	`409`	The terminal is deactivated.
`webhook_endpoint_disabled`	`409`	The webhook endpoint is disabled; enable it first.
`webhook_endpoint_limit_reached`	`400`	The account has the maximum number of webhook endpoints for this mode.
`webhook_url_forbidden`	`400`	The URL resolves to a private, loopback, link-local or otherwise reserved address.
`webhook_url_invalid`	`400`	The URL is not a valid absolute http(s) URL, uses http in live mode, or carries credentials.

`authentication_error`

Code	HTTP	Meaning
`api_key_expired`	`401`	The API key has passed its expiry (for example the overlap window of a rotation ended).
`api_key_invalid`	`401`	The API key is malformed or unknown.
`api_key_missing`	`401`	No API key was sent. Send `Authorization: Bearer <secret key>`.
`api_key_revoked`	`401`	The API key was revoked.

`idempotency_error`

Code	HTTP	Meaning
`idempotency_key_invalid`	`400`	The `Idempotency-Key` must be 1-255 printable ASCII characters.
`idempotency_key_required`	`400`	This endpoint moves money and requires an `Idempotency-Key` header.
`idempotency_key_reused`	`409`	The `Idempotency-Key` was already used with a different request (method, path or body).
`idempotency_request_in_progress`	`409`	A request with this `Idempotency-Key` is still being processed (or was interrupted). Do not retry with a new key before checking the outcome.

`api_error`

Code	HTTP	Meaning
`internal_error`	`500`	Something went wrong on ZyloPay's side. A retry with the same `Idempotency-Key` replays this error: check the object, then retry with a new key only if nothing happened.
`request_timeout`	`503`	The request exceeded its time budget and keeps running. Retry with the same `Idempotency-Key` (it never runs twice): you get its real outcome once it finished, `idempotency_request_in_progress` until then.
`service_unavailable`	`503`	A dependency is temporarily unavailable. A retry with the same `Idempotency-Key` replays this error: check the object, then retry later with a new key only if nothing happened.

`rate_limit_error`

Code	HTTP	Meaning
`rate_limited`	`429`	Too many requests for this API key. Wait for `Retry-After` seconds.

A declined or failed tap is not an HTTP error. The payment intent stays open (until it expires) and reports the reason in last_payment_error.code, and a payment_intent.payment_failed event is sent. The customer can try again, for example with another pass. refund_failed and settlement_reverted also appear as failure_code on a failed refund.

Code	Meaning
`pass_revoked`	The wallet pass was revoked.
`pass_frozen`	The wallet pass is frozen.
`pass_wrong_network`	The wallet pass was issued for the other network.
`authorization_required`	The wallet pass has no payment authorization; the payer must re-create it.
`authorization_expired`	The payer's spending approval expired; the payer must renew the pass.
`amount_exceeds_approval`	The amount is above the payer's spending approval.
`payer_frozen`	The payer's account is frozen.
`terminal_daily_limit`	The terminal reached its daily volume cap.
`risk_declined`	The payment was declined by risk rules.
`step_up_denied`	The payer or the cashier declined the confirmation request.
`step_up_expired`	The payer did not confirm in time.
`session_invalid`	The payment session was invalid, expired or already used.
`order_already_paid`	Another payment of this `order_id` is settled or in progress; nothing was charged by this attempt. Check that payment before charging again.
`credential_invalid`	The pass credential presented at the terminal is unknown or invalid.
`merchant_disabled`	The merchant account is disabled.
`kyb_required`	Live payments need an approved business verification.
`account_restricted`	The payer's account cannot be used with ZyloPay right now. Nothing was charged.
`settlement_failed`	The on-chain settlement failed; nothing was charged.
`settlement_reverted`	The on-chain transaction reverted; nothing was charged.
`refund_failed`	The on-chain refund failed; nothing was returned.
`processing_error`	The payment could not be processed.

Error codes

The error object

`permission_error`

`invalid_request_error`

`authentication_error`

`idempotency_error`

`api_error`

`rate_limit_error`

Payment decline codes

On this page

Error codes

The error objectCopy Anchor Link

permission_errorCopy Anchor Link

invalid_request_errorCopy Anchor Link

authentication_errorCopy Anchor Link

idempotency_errorCopy Anchor Link

api_errorCopy Anchor Link

rate_limit_errorCopy Anchor Link

Payment decline codesCopy Anchor Link

On this page

The error object

`permission_error`

`invalid_request_error`

`authentication_error`

`idempotency_error`

`api_error`

`rate_limit_error`

Payment decline codes