Rate Limits & Errors

Understanding rate limits, response headers, and error formats.

Rate Limit Tiers

Limits depend on your plan. See Pricing for plan details and prices.

Rate Limit Headers

Every response includes headers so you can track your usage in real time.

429 Too Many Requests

When you exceed a rate limit, the API returns a 429 status with details about which limit was hit.

{
  "detail": "Daily rate limit exceeded (20/20). Upgrade at /pricing for higher limits.",
  "upgrade_url": "/pricing",
  "limit_type": "daily"
}

The limit_type field indicates which limit was exceeded: minute, daily, or monthly.

Exempt Endpoints

The following endpoints are not rate-limited and do not count against your quotas:

• GET /v1/discover/* — Discovery endpoints
• GET /v1/stats — Statistics
• GET /v1/manifest — Manifest
• GET /v1/billing/* — Billing endpoints
• GET /v1/usage/* — Usage endpoints
• GET /v1/keys — Key management
• GET /auth/* — Authentication

HTTP Status Codes

Error Response Format

All errors follow a standard format with a detail field containing a human-readable message.

General errors

{
  "detail": "Human-readable error message"
}

Validation errors (400)

{
  "detail": [
    {
      "loc": ["body", "q"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}