Errors

Every error returns the same JSON shape:

{
  "error": "human readable message",
  "code": "SNAKE_CASE_CODE",
  "request_id": "8f0e1c54-...",
  "retry_after": 27
}

retry_after is only present on rate-limit errors and is always in seconds. request_id matches the X-Request-ID response header — include it in any support ticket.

Codes

HTTP	Code	Meaning
400	`BAD_REQUEST`	Missing or malformed query parameter.
401	`MISSING_API_KEY`	The `X-API-Key` header is absent.
401	`INVALID_API_KEY`	The key isn't recognized.
401	`REVOKED_API_KEY`	The key was revoked from the dashboard.
401	`EXPIRED_API_KEY`	The key passed its `expires_at`.
401	`UNAUTHORIZED`	Internal endpoint, wrong shared secret.
404	`NOT_FOUND`	Path doesn't match any route.
429	`RATE_LIMIT_MINUTE`	Per-minute quota exhausted.
429	`RATE_LIMIT_DAY`	Daily quota exhausted.
429	`RATE_LIMIT_IP`	IP-rate-limited (demo endpoints only).
500	`INTERNAL_ERROR`	Unexpected server error. Retry with backoff.

Recommended handling

401 INVALID_API_KEY / REVOKED_API_KEY — surface to the user, don't retry.
429 RATE_LIMIT_* — wait retry_after seconds, then retry.
5xx — exponential backoff up to 3 attempts.

Errors

Codes

Recommended handling

On this page