Errors & Limits
Every error has the same shape. Branch on error.code, not on the message, which may change.
Error shape
{
"error": {
"code": "invalid_request",
"message": "questions[1].name: duplicate question name \"agent\"",
"field": "questions[1].name"
}
}
// Optional members of "error":
// "field": the request path at fault
// "limit": which limit was exceeded (e.g. "max_text_tokens")
// "categories": phi_detected only, e.g. ["name", "date"] (never the values)
// A declined single-request escalation also has a top-level "decision".Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The body doesn't match the schema: unknown field, missing field, wrong type, a limit exceeded, a bad cursor or environment. See field and limit. |
| 400 | invalid_image | An image couldn't be fetched or decoded, or is too large or an unsupported format. field names the image. |
| 400 | idempotency_key_required | escalate: true without an Idempotency-Key header (or a key longer than 255 characters). |
| 401 | unauthorized | No usable credential reached the Decisions API (see the note on authentication errors below). |
| 401 | legacy_key | A personal-account key. Create a developer key (test or live) in the developer dashboard. |
| 402 | insufficient_credits | Available credit (balance minus reservations) doesn't cover the quote, after any auto-refill. On create with escalate: true, the saved preview is returned in decision. |
| 403 | developer_profile_required | The account has no developer profile yet. Open the developer dashboard once to create it. |
| 403 | developer_suspended | Developer access is suspended. (A suspended account's API key is usually refused earlier by the authentication layer; see below.) |
| 403 | production_not_active | Production preview or escalation on an account without production access. New previews are refused before provider work, with nothing stored. |
| 404 | not_found | No such decision or expert visible to this key, including decisions from the other environment and deleted previews. |
| 409 | price_exceeds_limit | quote.price_cents is above max_price_cents. The saved preview is returned in decision. |
| 409 | idempotency_conflict | This Idempotency-Key was already used with a different request body. |
| 409 | already_escalated | Escalate was repeated with a different reviewer override. |
| 409 | already_claimed | Cancel after a physician claimed the decision. |
| 409 | already_answered | Cancel after the physician answered. |
| 409 | decision_canceled | Escalate on a canceled decision. |
| 409 | decision_expired | Cancel on an expired preview. |
| 409 | decision_conflict | The decision changed state during your call (a race). Fetch it and retry if still appropriate. |
| 410 | quote_expired | Escalate after the quote's 24-hour window. Create a new preview. |
| 410 | decision_purged | An Idempotency-Key replay whose decision has since been deleted under the retention rules. |
| 413 | request_too_large | The request body exceeds 48 MB. |
| 422 | phi_detected | The screen found identifying information. categories lists what kind; nothing was stored. |
| 422 | no_matching_expert | No physician currently accepting decisions matches the reviewer selector. On create with escalate: true, the saved preview is returned in decision. |
| 429 | rate_limited | Too many create requests. Back off and retry. |
| 429 | sandbox_limit | Test keys include 200 requests per day, shared with the Prescribing API and the playground. Resets within 24 hours; production keys aren't subject to it. |
| 429 | preview_limit | Production accounts include 1,000 create requests (previews and immediate escalations) per 24 hours. Retry after the Retry-After interval; contact hello@appendix.com to raise it. |
| 500 | internal_error | Unexpected error. Retry with backoff; with escalate: true, reuse the same Idempotency-Key. |
| 503 | phi_screen_unavailable | The screen couldn't complete. Fails closed; nothing was stored. Retry. |
| 503 | preview_unavailable | A temporary problem on our side generating or saving the preview. Nothing was stored. Retry: a request that breaks a documented limit gets a 400 instead, so this error is always worth retrying. |
| 503 | escalation_unavailable | The escalation couldn't be committed. Nothing was reserved or queued. Retry (same Idempotency-Key on create). |
| 503 | unavailable | A temporary storage problem on a read, list or cancel. Retry. |
| 503 | sandbox_busy | The test environment is temporarily at capacity. Retry later (see Retry-After). |
Authentication errors. A missing or invalid key, or a key on a suspended account, is rejected before the request reaches the Decisions API, with a shorter body whose error is a plain string: 401 {"error": "missing authentication"}, 401 {"error": "authentication failed"} or 403 {"error": "developer access suspended"}. Check typeof error === "string" before reading error.code.
Treat unknown codes by their HTTP status. 5xx errors on create never leave a partial decision behind; a retry is always safe.
Limits
| Limit | Value |
|---|---|
| Questions per request | 1–50 (3 included in the price; $1.00 each after that) |
| Question text (instructions) | ≤ 500 characters per question |
| Question name | Nonempty, unique, ≤ 128 characters, not starting with _appendix |
| Choices per choice question | 2–255, unique; value a nonempty string (≤ 1,024 characters) or a boolean |
| Levels per score question | 2–10; label nonempty, ≤ 1,024 characters |
| Choice / level description | ≤ 4,096 characters |
| Text and JSON tokens (o200k_base) | ≤ 10,000 per request, across input and questions |
| Text and JSON characters | ≤ 100,000 per request across the same fields, checked before tokens are counted |
| Images | ≤ 3 per request across input and questions; JPEG, PNG, HEIC, GIF or WebP; ≤ 10 MB and ≤ 40 megapixels each; https or base64 data URL |
| Image URL | https only, ≤ 4,096 characters |
| input messages | ≤ 32 |
| Content parts per message or instructions | ≤ 64 |
| Any single text string | ≤ 256 KiB |
| input_json data | Object or array of objects; ≤ 32 levels deep, ≤ 10,000 values, ≤ 256 KiB canonical |
| external_id | ≤ 256 characters, no control characters |
| reviewer fields | empty expert_ids and specialties lists only; turnaround "24h" only |
| Request body | ≤ 48 MB |
| Idempotency-Key | 1–255 characters; remembered 7 days per account and environment |
| Physician comment | ≤ 280 Unicode code points per answer |
| List page size | limit 1–100, default 20 |
| Create rate | 120 requests per minute per developer account |
| Production daily allowance | 1,000 create requests per developer account per 24 hours (429 preview_limit) |
| Test daily allowance | 200 requests per developer account per 24 hours, shared with the Prescribing API (429 sandbox_limit) |
| Quote validity | 24 hours from preview |
| Physician turnaround | 24 hours from escalation |
Character limits count Unicode code points. Exceeding a limit returns 400 invalid_request with error.field and, for the main limits, error.limit (for example max_questions, max_question_chars, max_text_chars, max_text_tokens, max_images, image_size, json_depth, json_values, json_bytes, external_id_length).