L402 Error Codes

Reference for HTTP status and error codes returned by Axo Pay middleware.

All middleware denials return JSON in this shape:

{
  "error": {
    "code": "error_code",
    "message": "Human-readable message"
  }
}

Server Error Reference (`@axobot/pay`)

HTTP	`error.code`	Meaning
402	`payment_required`	No valid credential provided. Client must pay invoice and retry.
401	`invalid_credential`	Token signature is invalid or malformed.
401	`invalid_payment_proof`	Preimage does not match the payment hash.
403	`resource_mismatch`	Token was issued for a different route.
403	`amount_mismatch`	Token was issued for a different price.
403	`token_expired`	Token is past `expiresAt`.
500	`configuration_error`	Missing middleware configuration (for example `ZBD_API_KEY`).
500	`pricing_error`	Dynamic pricing function failed.
502	`invoice_creation_failed`	Upstream invoice creation failed.

Common Client-Side Failures (`@axobot/fetch`)

These are thrown as runtime errors (not structured HTTP middleware errors):

requestChallenge expects a 402 response
Invalid payment challenge
Payment required: <amount> sats exceeds limit of <max> sats
Payment response missing preimage and no settlement poller is configured
Payment <id> failed: <reason>
Payment <id> did not settle within <timeout>ms

Tip

For robust clients, catch these errors and map them to retries, budget policies, or user-visible payment actions.

Overview

Understand the full L402 protocol flow in the Axo stack.

Protect Routes

Implement server-side route protection and challenge issuance.

Call Paid APIs

Build clients that solve 402 challenges automatically.

Call Paid APIs

Handle 402 challenges and pay invoices automatically with Axo Fetch or axo fetch.

Cloudflare Workers + Axo

Add Axo payments to any Cloudflare Workers app with the Agents SDK.

On this page

Server Error Reference (@axobot/pay)Common Client-Side Failures (@axobot/fetch)Related Pages