Error Handling

All error responses use a consistent JSON envelope.

Error envelope

{
  "error": {
    "code": "quota_exhausted",
    "message": "Monthly quota has been depleted.",
    "detail": {}
  }
}

HTTP status codes

Code	Meaning
200	OK
304	Not Modified (ETag match; quota still decremented)
400	Bad Request — invalid filter or parameter
401	Unauthorized — missing or invalid token
402	Payment Required — billing quota exhausted
404	Not Found — resource does not exist or is not public
429	Too Many Requests — rate limit exceeded
500	Internal Server Error

Distinguishing 402 vs 429

• 402 — monthly quota depleted. Retry after quota reset or account top-up.
• 429 — requests-per-minute cap. Retry after Retry-After seconds.

See Rate Limits for retry strategies.