Skip to main content

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

StatusCodeMeaning
400invalid_requestThe body doesn't match the schema: unknown field, missing field, wrong type, a limit exceeded, a bad cursor or environment. See field and limit.
400invalid_imageAn image couldn't be fetched or decoded, or is too large or an unsupported format. field names the image.
400idempotency_key_requiredescalate: true without an Idempotency-Key header (or a key longer than 255 characters).
401unauthorizedNo usable credential reached the Decisions API (see the note on authentication errors below).
401legacy_keyA personal-account key. Create a developer key (test or live) in the developer dashboard.
402insufficient_creditsAvailable 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.
403developer_profile_requiredThe account has no developer profile yet. Open the developer dashboard once to create it.
403developer_suspendedDeveloper access is suspended. (A suspended account's API key is usually refused earlier by the authentication layer; see below.)
403production_not_activeProduction preview or escalation on an account without production access. New previews are refused before provider work, with nothing stored.
404not_foundNo such decision or expert visible to this key, including decisions from the other environment and deleted previews.
409price_exceeds_limitquote.price_cents is above max_price_cents. The saved preview is returned in decision.
409idempotency_conflictThis Idempotency-Key was already used with a different request body.
409already_escalatedEscalate was repeated with a different reviewer override.
409already_claimedCancel after a physician claimed the decision.
409already_answeredCancel after the physician answered.
409decision_canceledEscalate on a canceled decision.
409decision_expiredCancel on an expired preview.
409decision_conflictThe decision changed state during your call (a race). Fetch it and retry if still appropriate.
410quote_expiredEscalate after the quote's 24-hour window. Create a new preview.
410decision_purgedAn Idempotency-Key replay whose decision has since been deleted under the retention rules.
413request_too_largeThe request body exceeds 48 MB.
422phi_detectedThe screen found identifying information. categories lists what kind; nothing was stored.
422no_matching_expertNo physician currently accepting decisions matches the reviewer selector. On create with escalate: true, the saved preview is returned in decision.
429rate_limitedToo many create requests. Back off and retry.
429sandbox_limitTest 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.
429preview_limitProduction 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.
500internal_errorUnexpected error. Retry with backoff; with escalate: true, reuse the same Idempotency-Key.
503phi_screen_unavailableThe screen couldn't complete. Fails closed; nothing was stored. Retry.
503preview_unavailableA 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.
503escalation_unavailableThe escalation couldn't be committed. Nothing was reserved or queued. Retry (same Idempotency-Key on create).
503unavailableA temporary storage problem on a read, list or cancel. Retry.
503sandbox_busyThe 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

LimitValue
Questions per request1–50 (3 included in the price; $1.00 each after that)
Question text (instructions)≤ 500 characters per question
Question nameNonempty, unique, ≤ 128 characters, not starting with _appendix
Choices per choice question2–255, unique; value a nonempty string (≤ 1,024 characters) or a boolean
Levels per score question2–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 URLhttps only, ≤ 4,096 characters
input messages≤ 32
Content parts per message or instructions≤ 64
Any single text string≤ 256 KiB
input_json dataObject or array of objects; ≤ 32 levels deep, ≤ 10,000 values, ≤ 256 KiB canonical
external_id≤ 256 characters, no control characters
reviewer fieldsempty expert_ids and specialties lists only; turnaround "24h" only
Request body≤ 48 MB
Idempotency-Key1–255 characters; remembered 7 days per account and environment
Physician comment≤ 280 Unicode code points per answer
List page sizelimit 1–100, default 20
Create rate120 requests per minute per developer account
Production daily allowance1,000 create requests per developer account per 24 hours (429 preview_limit)
Test daily allowance200 requests per developer account per 24 hours, shared with the Prescribing API (429 sandbox_limit)
Quote validity24 hours from preview
Physician turnaround24 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).