Errors
The API uses conventional HTTP status codes and returns a typed JSON envelope so failures are easy to branch on programmatically.
Error envelope
Errors share a consistent shape — a top-level error object with a machine-readable code and a human message, plus context fields where useful:
{
"error": {
"code": "INVALID_ADDRESS",
"message": "The provided contract address is not valid for the specified chain",
"field": "project_address"
}
}Status codes
| Status | Code | Meaning & fix |
|---|---|---|
| 400 | INVALID_ADDRESS | Address malformed for the chain, or an invalid chain. Validate format before sending. |
| 402 | PAYMENT_REQUIRED | No balance / payment for a paid endpoint. Fund the account or complete the x402 flow. |
| 404 | PROJECT_NOT_FOUND | No token found at that address on that chain. Re-check the chain and address. |
| 429 | RATE_LIMIT_EXCEEDED | Window exhausted. Wait retry_after_seconds. See Rate limits. |
| 500 | ANALYSIS_FAILED | An upstream data source was unavailable. Retry once after a short delay. |
Examples
402 — Payment required
{
"error": {
"code": "PAYMENT_REQUIRED",
"message": "Payment of $1.00 required",
"payment_requirements": { "amount": "1.00", "currency": "USDC", "network": "base-mainnet" }
}
}404 — Project not found
{
"error": {
"code": "PROJECT_NOT_FOUND",
"message": "No project found at address 0x… on ethereum",
"chain": "ethereum",
"address": "0x…"
}
}Handling guidance
- Check the status code first, then branch on
error.codefor specifics. - 402: let your x402 client settle payment and retry automatically.
- 429: back off for
retry_after_secondsbefore retrying. - 500: retry once after ~5s; if it persists, the upstream chain data is likely degraded.