Rate limits & Errors

Public API endpoints may enforce rate limits and return consistent JSON errors.

Rate limiting

When rate limiting is enabled, responses include these headers:

• X-RateLimit-Limit: maximum requests allowed in the window
• X-RateLimit-Remaining: remaining requests in the window
• X-RateLimit-Reset: unix timestamp (seconds) when the window resets

Headers schema

429 example

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1760000000

{ "error": "Rate limit exceeded" }

Common errors

• 401: missing/invalid API key (e.g. missing Authorization header, invalid format, revoked, expired)
• 403: insufficient scope (permissions)
• 400: invalid query parameters (includes validation details)
• 404: resource not found
• 500: internal server error

Error schema

Most error responses follow a simple shape:

type PublicApiErrorResponse = {
  error: string;
};

Validation error schema (400)

When query parameters fail validation, the API includes details (Zod issues).

type PublicApiValidationErrorResponse = {
  error: "Invalid query parameters";
  details: Array<{
    path: Array<string | number>;
    message: string;
    code?: string;
  }>;
};

400 example

{
  "error": "Invalid query parameters",
  "details": [
    { "path": ["limit"], "message": "Number must be less than or equal to 100" }
  ]
}