Errors

Paybytoken uses HTTP status codes and a machine-readable error type. Most rejected API requests return:

{
  "error": {
    "code": 400,
    "type": "validation_error",
    "message": "currency is required"
  }
}

Treat the HTTP status as authoritative. Error messages are for diagnosis and may change; branch on the status and type instead of matching message text.

Status codes

Retry safely

Use exponential backoff with jitter for 429, transient 5xx responses and network timeouts. Cap the number of attempts and keep the customer informed.

Reads are safe to retry. For a mutation that accepts or requires Idempotency-Key, reuse the exact same key only with the exact same logical request; the Node SDK exposes this as { idempotencyKey }. Do not blindly repeat other writes after a timeout because the original request may have completed. Retrieve the related resource before deciding whether another action is safe.

Webhook delivery is asynchronous and can repeat. Store each event ID with a unique constraint and make fulfillment idempotent.

Log useful context

Record:

• the response X-Request-Id;
• the HTTP method and path;
• the status and error type; and
• your own order or correlation ID.

Never record merchant API keys, chk_client_... values, webhook secrets, signatures or complete one-time payment addresses.

For embedded browser failures, also see Checkout troubleshooting.