Error Codes

Every error response follows the same JSON shape, with an HTTP status code and a machine-readable error field for programmatic handling.

Error shape

{
  "error": "rate_limited",
  "message": "Rate limit exceeded for plan 'free'. Upgrade for higher limits.",
  "retry_after_seconds": 60
}

Status codes

400bad_request

Malformed request body — missing or invalid fields.

401unauthorized

Missing, invalid, or revoked API key / JWT.

403forbidden

Valid credentials, but not permitted for this action or role.

404not_found

The session, org, or resource doesn't exist.

429rate_limited

Requests-per-minute cap exceeded for your plan. See Retry-After header.

429quota_exceeded

Monthly session quota exceeded for your plan — distinct from rate limiting. Enforced at ingestion (POST /v1/ingest) only, not on read endpoints.

500internal_error

Unexpected server-side failure. Safe to retry with backoff.

⚠️

rate_limited and quota_exceeded are both HTTP 429 but mean different things — see Rate Limits for the distinction and how to handle each.