Docs

Errors

Predictable error envelope, semantic status codes, idempotency keys.

Envelope

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly API unit quota exceeded for plan 'starter'.",
    "request_id": "req_01HF7..."
  }
}

Status codes

400 invalid_request — bad payload

401 unauthenticated — missing / invalid bearer

403 forbidden — scope or plan does not allow this endpoint

404 not_found — resource not present

409 conflict — idempotency conflict

422 validation_failed — schema validation

429 rate_limited — slow down

402 payment_required — AI credits exhausted

5xx — transient on our side, safe to retry with backoff

Idempotency

For POSTs, send Idempotency-Key: <uuid>. Repeats within 24h return the original response.