Error Handling

The API returns JSON error responses for invalid requests.

Missing API Key

Cause: the Authorization header was not provided.

{
  "message": "Please provide your api key",
  "error": "Bad Request",
  "statusCode": 400
}

Fix: include your merchant API key.

Authorization: <merchant-api-key>

Missing Payment Signature

Cause: POST /api/x402/submit was called without the payment-signature header.

{
  "message": "PAYMENT-SIGNATURE header is required",
  "error": "Bad Request",
  "statusCode": 400
}

Fix: base64-encode the signed x402 payload and send it as:

payment-signature: <base64-encoded-X402SignaturePayload>

Multiple Payment Signature Headers

Cause: more than one payment-signature value was sent.

{
  "message": "PAYMENT-SIGNATURE header must be a single value",
  "error": "Bad Request",
  "statusCode": 400
}

Fix: send exactly one payment-signature header.

Insufficient Permit2 Allowance

Cause: the payer wallet has not approved the Permit2 contract to spend the token. This error occurs on Permit2 chains (BSC, Ethereum, or non-USDC tokens).

{
  "message": "x402: insufficient Permit2 allowance — sender must approve Permit2 contract",
  "error": "Bad Request",
  "statusCode": 400
}

Fix: run the one-time ERC-20 approval before submitting. See Permit2 Approval for the complete guide.

// One-time approval — run once per wallet/token/chain
const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3';
await erc20.approve(PERMIT2_ADDRESS, ethers.MaxUint256);

Validation Errors

Cause: the request body does not match the required field types.

Common validation issues:

• amount must be a positive number.

• to and from must be valid Ethereum addresses.

• nonce is required.

• validBefore must be a number greater than or equal to 0.

• resourceUrl is required.

• resourcesDescription is required.

• token must be a supported token for the given network.

• network must be a supported network.

Invalid Base64 Payload

Cause: the payment-signature value is not valid base64 JSON.

Fix:

1. Create the signature payload as JSON.

2. Convert it to UTF-8.

3. Encode it as base64.

4. Send the encoded string as the header value.

const paymentSignature = Buffer.from(
  JSON.stringify(signaturePayload),
  'utf8',
).toString('base64');

Authorization Expired

Cause: the validBefore timestamp in the signed authorization has passed by the time the submission is processed.

Fix: use now + maxTimeoutSeconds from the /initiate response as validBefore, and submit promptly after signing. The authorization window is typically 60 seconds.