Errors

Table of Contents

Status codes

  • 400 - malformed request (bad JSON, missing required fields). Not charged.
  • 401 - missing or invalid bearer token.
  • 402 - insufficient credit balance (see below). Not charged.
  • 413 - payload too large. Not charged. For the model modes the limit is published in TOKENS (max_input_tokens, counted with the tokenizer named in GET /v1/limits); deterministic mode is capped in characters. GET /v1/limits is the only source you need: never infer a cap.
  • 422 - structurally valid request that fails validation. Not charged.
  • 500 - server-side failure. If a failure occurs after billing, the charge is refunded automatically.

Validation and authentication failures happen before billing; a request rejected with 400/401/413/422 never touches your balance.

HTTP 402 - insufficient balance

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Insufficient credit balance",
    "details": {
      "estimated_cost": 0.00762,
      "current_balance": 0.00300
    }
  }
}

An agent can use estimated_cost and current_balance to decide between topping up and shrinking the request.

Timeout tiers

  • Fast tier (5 s budget): health and small public GET endpoints.
  • Processing tier (35 s budget): /v1/compress and the account endpoints.

A request that exceeds its budget returns 408 REQUEST_TIMEOUT. The 35-second processing budget bounds the envelope of a single compress call; measured per-mode, per-size timings are in latency.