Stats API
Menu
Public preview View coverage
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
{
  "error": {
    "code": "validation_error",
    "message": "The request parameters are invalid.",
    "details": {
      "limit": "Must be between 1 and 100."
    }
  }
}

Status codes

HTTP Use
400 Malformed request syntax or an invalid filter combination.
401 Missing, invalid, or revoked API key.
403 Authenticated account lacks active access.
404 Endpoint or stable resource ID was not found.
405 HTTP method is not supported for this route.
422 A field is present but cannot be accepted.
429 Rate limit or monthly quota exhausted.
503 A required service such as the normalized store is unavailable.

Retry policy

  • Do not retry 400, 401, 403, 404, or 422 without changing the request.
  • Retry 429 only after the applicable reset, with jitter.
  • Retry 503 with bounded exponential backoff.
  • Log the response request ID when present so support can trace a failure.