Errors and retries - Zahlo Merchant Developer Docs

Errors include a machine-readable error code, a human-readable message, and when available a request ID and field details. Log the request ID and your own operation ID, never the API key, client token, webhook secret, or payment-field data. Redact response bodies before sending them to error tracking.

Retry policy

Retry network failures and temporary server failures with bounded exponential backoff.
Reuse the same Idempotency-Key for a retried create request.
Do not retry validation or authentication errors without changing the request or credentials.
Treat an accepted request with an unknown response as pending until you reconcile it by ID.

Common categories

Category	Action
`400` validation	Fix the request and do not retry unchanged
`401` authentication	Check API key or client token scope
`404` missing resource	Check the environment and resource ID
`409` conflict	Retrieve current state and reconcile
`429` rate limit	Back off and retry with the same idempotency key
`5xx` temporary failure	Retry safely, then reconcile before creating again

Payment-specific outcomes

An accepted checkout or payment request may remain pending while a customer completes a redirect, wallet approval, or bank authorization. An invalid method or expired session requires a new customer action; an unknown network result requires retrieval by ID. Do not classify an ambiguous result as failed and charge again.