Error reference

Handle
API errors

Application errors use the HTTP status and a JSON detail object. Display message to the user. Use code to decide how your application responds.

HTTP status codesStructured errors

On this page

Error response

Application errorJSON

{
  "detail": {
    "code": "text_too_long",
    "message": "35,001 characters is over the 35,000 limit for one run."
  }
}

Some errors add details. A low balance looks like this:

Low balance errorJSON

{
  "detail": {
    "code": "insufficient_balance",
    "message": "Available balance is 0.01 USD. This run needs about 0.05 USD reserved until the final cost is known.",
    "details": {
      "available_usd": "0.010000",
      "hold_required_usd": "0.050000",
      "is_estimate": true
    }
  }
}

Status codes

HTTP	Code	When
400	`invalid_request`	The body is missing prose, quality is not `low`, `standard`, or `high`, or an estimate has neither `text` nor `word_count`.
400	`text_too_long`	The draft exceeds `restrictions.max_chars_per_run` returned by `GET /v1/me`.
400	`confirmation_required`	`DELETE /v1/runs` without `?confirm=true`.
401	`unauthenticated`	Missing or unknown API key, or no session.
402	`insufficient_balance`	The available balance cannot cover the hold. Nothing is queued.
403	`account_suspended`	The account cannot call the API.
403	`forbidden`	An API key tried to create another API key.
403	`insufficient_scope`	The API key lacks the scope this endpoint needs. `details.required_scope` names it: `humanize` for runs, `detect` for checks, `billing:read` for billing.
404	`not_found`	That run or key is not yours, or does not exist.
409	`run_in_progress`	Delete was called on a queued or running run. Cancel it first.
422		The request JSON is invalid. Unknown fields such as `model` or `mode` are rejected here. The body is a validation list, not a `code`.
429	`rate_limited`	Too many requests. Follow the `Retry-After` header. `details.retry_after_seconds` says the same thing.
503	`provider_unavailable`	The account is not ready to run yet. Try again shortly, and check `can_run_reason` on `GET /v1/me`.

Validation errors

A 422 means validation failed before a run was created. The usual cause is a field the API no longer accepts.

Validation errorJSON

{
  "detail": [
    {
      "type": "extra_forbidden",
      "loc": ["body", "model"],
      "msg": "Extra inputs are not permitted"
    }
  ]
}