AgentPay logoAgentPay
Discord

Errors & troubleshooting

The AgentPay API uses standard HTTP status codes and returns a JSON body with an error field when something goes wrong. This page lists common errors and how to resolve them.

HTTP status codes

  • 200 — Success. Response body contains the requested data or payment result.
  • 201 — Created. Used for POST /api-keys and POST /wallets.
  • 204 — No content. Used for DELETE /wallets/:id on success.
  • 400 — Bad request. Invalid or missing parameters, or business rule violation (e.g. duplicate API key).
  • 401 — Unauthorized. Missing or invalid X-Api-Key header.
  • 402 — Payment required / payment failed. Returned by POST /v1/pay when verification or settlement fails. Body may include facilitator details.
  • 404 — Not found. Route or resource does not exist.
  • 429 — Too many requests. Monthly payment limit for your plan has been reached. Response includes upgradeUrl; upgrade at the dashboard to increase the limit.
  • 500 — Internal server error. Logs on the server will have more detail; retry with backoff.

Common error messages

API key not resolved (401)

The X-Api-Key header is missing, malformed, or does not match any stored key. Ensure you send X-Api-Key: pk_... on every authenticated request. If you use the dashboard, copy the key from the API Keys page and keep it secret.

paymentRequiredHeader (base64) required (400)

POST /v1/pay was called without a valid paymentRequiredHeader in the body. The SDK normally supplies this from the 402 response; if you call the API manually, decode the paid API's payment-required header and send it as base64.

No wallet for network base (400)

The payment requirements specify a network (e.g. base) for which your API key has no wallet. Create one with POST /wallets and body { "network": "base" }, then retry the payment.

Payment verification failed / settlement failed (402)

The x402 facilitator rejected the payment (e.g. insufficient balance, invalid payload, or network issue). Check the response body for facilitator details. Ensure your facilitator URL and optional API key are correct in the API environment. For development, confirm the facilitator is reachable and that wallet and asset configuration match the requirements.

That API key already exists (400)

You sent a custom key in POST /api-keys that collides with an existing key. Omit key to let the API generate a new one, or use a different value.

Payment limit reached for your plan this month (429)

Your API key is tied to a plan with a monthly payment limit (FREE, Developer, Agency). The limit has been reached. The response body includes upgradeUrl (e.g. to the dashboard Plan page). Upgrade your plan to increase the limit.

SDK and integration tips

  • Use environment variables for apiKey and baseUrl so you never commit secrets.
  • If the SDK throws after a 402, inspect the error message and the upstream 402 response; often the issue is an invalid or unsupported payment-required format.
  • For spend and wallet listing, ensure the same API key is used that created the wallets and made the payments.