Errors
Errors return a JSON body with an error string alongside a conventional HTTP status code.
◆ Status codes
| Status | Meaning | Retry |
|---|---|---|
| 400 | A query parameter is malformed (wrong type, out-of-range value, unknown sortBy). | Don't retry. Fix the request. |
| 401 | The x-api-key header is missing or carries an unknown / revoked key. | Don't retry. Verify the key in the dashboard. |
| 403 | API Gateway rejected the request (missing or invalid x-api-key before it reaches the API). | Don't retry. Verify the key in the dashboard. |
| 404 | No resource matches the path parameter (event id, coin slug), or the event is outside your tier date window. | Don't retry. Verify the identifier or widen your date filters. |
| 429 | You've exceeded your monthly quota or short-term rate limit (enforced by AWS API Gateway usage plans). | Backoff and retry. Honor Retry-After when present. |
| 500 | Unexpected server-side failure. | Retry once after a few seconds. If it persists, contact support. |
| 503 | Temporary outage or scheduled maintenance. | Retry with exponential backoff (e.g. 1s, 2s, 4s, capped at 30s). |
◆ Response shape
{ "error": "Invalid limit" }
◆ Retry strategy
- 4xx are not transient. Don't retry. Fix the request or the credential.
- 429 needs backoff. Rate limits are enforced by AWS API Gateway usage plans per tier. Most clients hitting 429 need to add backoff or cache responses.
- 5xx with exponential backoff. 1s → 2s → 4s → 8s, capped at 30s. Give up after 5 attempts and surface the failure.