Error Reference
Machine-readable API error codes and diagnostics contract for checkout, auth, and merchant endpoints.
Error responses follow one contract: error.code, message, requestId, retryable,docsUrl, and optional details.
Use error.code as the primary integration key in your backend logic, then map retryable and HTTP status to retry/alert behavior.
Diagnostics flow: log requestId on every failed request, branch retry behavior using retryable, and surfacedocsUrl in internal tooling so operators can jump directly to the relevant error anchor.
Checkout
AUTH_MISSING_BEARER_TOKEN
Send `Authorization: Bearer <API_KEY>` from backend.
AUTH_INVALID_API_KEY
Regenerate API key and verify account active state.
MERCHANT_WALLET_NOT_LINKED
Link settlement wallet before creating checkout session.
CHECKOUT_VALIDATION_FAILED
Inspect `error.details` and fix payload fields.
CHECKOUT_DUPLICATE_ORDER_ID
Use unique orderId per business.
MAINTENANCE_MODE_ACTIVE
Respect `Retry-After` and retry after maintenance.
INTERNAL_SERVER_ERROR
Retry if safe and share requestId with support.
Auth
AUTH_MISSING_REQUIRED_FIELDS
Provide all required payload fields for the auth endpoint.
AUTH_INVALID_CREDENTIALS
Re-check email/password pair and try again.
AUTH_EMAIL_NOT_VERIFIED
Verify account email before login.
AUTH_PROFILE_SETUP_REQUIRED
Complete profile setup before password login.
AUTH_ACTIVATION_TOKEN_MISSING
Submit activation token in request payload.
AUTH_ACTIVATION_TOKEN_INVALID
Request a new activation link and retry.
AUTH_WALLET_SIGNATURE_INVALID
Re-sign challenge message from the same wallet.
AUTH_PROFILE_EMAIL_CONFLICT
Use a different email address for this account.
AUTH_MERCHANT_NOT_FOUND
Confirm businessId mapping and account existence.
AUTH_EMAIL_ALREADY_VERIFIED
Skip resend flow because verification is complete.
Merchant
MERCHANT_UNAUTHORIZED
Authenticate first and ensure auth-token cookie is valid.
MERCHANT_EXPORT_VALIDATION_FAILED
Use valid export query values (`status`, `from`, `to`) with ISO date format.
MERCHANT_INVALID_ACTION
Use supported action values (`link` or `unlink`).
MERCHANT_MISSING_CRYPTO_PROOFS
Provide `publicKey`, `signature`, and `message` for wallet linking.
MERCHANT_WALLET_SIGNATURE_INVALID
Regenerate wallet signature and retry with matching key.
MERCHANT_WALLET_ALREADY_LINKED
Use a wallet not owned by another merchant account.
Internal Ops
INTERNAL_CONFIRMATION_MISSING_FIELDS
Send both `transactionId` and `signature` in confirmation payload.
INTERNAL_CONFIRMATION_REJECTED
Inspect transaction state and signature validity before retrying confirmation.
INTERNAL_RPC_TELEMETRY_INVALID_PAYLOAD
Include `operation`, `endpoint`, and `primaryEndpoint` when sending telemetry events.
INTERNAL_CRON_UNAUTHORIZED
Pass valid cron secret via `x-cron-secret` or `Authorization: Bearer <secret>`.