Guides
Error handling
Every error the API returns and what to do about it.
All errors are JSON: { "error": "message" }.
Client errors (4xx)
| Status | When | Action |
|---|---|---|
| 400 | Unknown service/country/operator, malformed body | Check against /v1/services, /v1/countries, /v1/operators |
| 400 | accepted in your payment payload doesn't match the requirements (scheme, network, asset, payTo, or amount too low) | Re-read the 402 and echo requirements exactly |
| 401 | Wrong or missing accessToken | Use the token returned at order time |
| 402 | Payment verification failed (bad signature, expired authorization, insufficient USDC/allowance) | Fix the payment and retry — nothing was charged |
| 404 | Activation id not found | Check the id |
| 409 | NO_NUMBERS — no inventory for that combination | Not charged. Try another country/operator, or retry later |
| 409 | Cancel/retry on a finished activation | Inspect status first |
Server errors (5xx)
| Status | When | Action |
|---|---|---|
| 500 | Misconfiguration on our side | Contact support |
| 502 | Temporary service error, price feed failure, or settlement failure | Safe to retry. Settlement failures retry automatically on the next poll — you will never be double-charged |
| 503 | NO_BALANCE — activation capacity temporarily exhausted | Not charged. Retry later |
Idempotency & safety rules for agents
- Paying twice for the same order is impossible — each activation binds to one verified payment payload.
- Settlement happens once — repeated polls after
completedreturn the stored code and never settle again. - Never charged for failure —
cancelled,expired, and failed orders always settle $0. - Polling is free — status endpoints are not x402-gated.