# API errors

Handle Stats API HTTP statuses and stable machine-readable error codes.

Canonical URL: https://stats-api.com/docs/errors

Developer guide

## Errors your code can reason about.

Every API error has an HTTP status plus a stable code, human-readable message, and optional details object.

## Error shape

Example

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "limit must be between 1 and 100.",
    "details": {
      "parameter": "limit"
    }
  }
}
```

## Status codes

| HTTP | Use |
| --- | --- |
| 401 · invalid_api_key | Bearer key is missing, malformed, unknown, or revoked. |
| 403 · subscription_inactive | Bearer key is valid, but its account has no current API entitlement. |
| 404 · not_found | Endpoint or stable resource ID was not found. |
| 405 · method_not_allowed | HTTP method is not supported for this route. |
| 422 · invalid_parameter | A documented query parameter has an invalid value. |
| 422 · unknown_parameter | A query parameter name is outside the documented contract. |
| 429 · rate_limit | Per-minute request allowance is exhausted. |
| 429 · monthly_quota | Billing-period request allowance is exhausted. |
| 429 · free_allowance_exhausted | The entire one-time free allowance is used. Upgrade to continue; X-Quota-Reset is 0 and there is no automatic reset or Retry-After. |
| 503 · service_unavailable | A required service such as the normalized store is unavailable. |

## Retry policy

- Do not retry 401, 403, 404, 405, or 422 without changing credentials, billing state, or the request.
- Retry rate_limit or monthly_quota 429 responses only after the applicable reset, with jitter. Do not automatically retry free_allowance_exhausted: its details.reset_at is null and the account needs a paid plan to continue.
- Retry 503 with bounded exponential backoff.
- Log the response request ID when present so support can trace a failure.

---

Markdown version of https://stats-api.com/docs/errors. Site index: https://stats-api.com/llms.txt · Full documentation and OpenAPI contract: https://stats-api.com/llms-full.txt · AI usage policy: https://stats-api.com/ai.txt