{ "error": { "code": "...", "message": "..." } }
| HTTP | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR | A malformed handle, address or query parameter. |
| 400 | BAD_REQUEST | The request cannot be served as sent. |
| 401 | UNAUTHORIZED | Missing or invalid API key. |
| 402 | QUOTA_EXCEEDED | Out of credits. Top up at partner.fomoscan.sh. |
| 402 | REVEAL_LIMIT_REACHED | The plan’s monthly reveal limit is reached. Credits cannot buy past it. |
| 403 | FORBIDDEN | The key may not perform this action. |
| 403 | FORBIDDEN_SCOPE | Your key is not provisioned for this endpoint. |
| 403 | FREE_TIER_DISABLED | The key has no allowance. Buy a plan to continue. |
| 403 | SAMPLE_SET_ONLY | A free key asked for a wallet outside the sample set. |
| 403 | WEBSOCKET_PLAN_REQUIRED | Your plan has no WebSocket access. Sockets come with Growth and up. |
| 404 | NOT_FOUND | No answer for that handle, id or wallet, or no such route. |
| 409 | CONFLICT | The request conflicts with one already accepted. |
| 429 | RATE_LIMITED | Per-minute limit exceeded. Retry after retryAfter seconds. |
| 500 | INTERNAL_ERROR | Our fault. Retry. If it persists, contact support with the path and the time. |
| 503 | OVERLOADED | We are shedding load. Retry. |
| 503 | B2B_DISABLED | The API is switched off on this deployment. |
| 504 | TIMEOUT | The answer did not arrive in time. Retry. |
{ "error": { "code": "RATE_LIMITED", "message": "rate limit exceeded; retry later", "retryAfter": 12 } }
404 on a lookup means “no answer today”. Cache it briefly and ask again later.
A 404 is charged at the miss price. 401, 403, 429 and 5xx answers are
not charged.