Errors & Status Codes
Every error returns the same JSON envelope, and the HTTP status always matches the code field:
{ "error": "Human-readable message", "code": 400 }| Status | Meaning | What to do |
|---|---|---|
400 | Bad request — invalid parameters | Fix the request (check the mint/address format and query params) |
401 | Unauthorized — missing or invalid API key | Check the Authorization: Bearer header |
403 | Forbidden — your tier can’t access this endpoint | Upgrade, or use a lower-tier endpoint |
404 | Not found — the resource doesn’t exist | Verify the mint or wallet address |
429 | Rate limited | Back off and retry (see Tiers & Rate Limits) |
500 | Internal error | Retry; if it persists, reach out |
503 | Service unavailable — an upstream dependency is down | Retry with backoff |
⚠️
Branch on the HTTP status code, not on the response body. 429 and 503 are worth retrying with backoff; 400, 401, and 403 are not — fix the request or the key first.