Errors

Every error is a JSON body with a stable type and code. The type tells you the class of problem and maps one to one to the HTTP status. The code tells you the exact reason. Errors before admission never charge your balance, and server errors after admission are refunded.

The error envelope#

{
  "error": {
    "type": "validation",
    "code": "state_path_not_found",
    "message": "Question 'spoed' refers to {{bericht.txt}}, which is not in the state.",
    "param": "questions.spoed.instructions",
    "request_id": "req_01M5CJXHG0M9S346Q3D25VT4F5"
  }
}

Status codes#

Codes in detail#

Which error comes first#

Dex checks a request in this order and stops at the first failure:

1. Authentication (401), then scope (403).
2. Body size (413 body_too_large), content type (400 unsupported_media_type), then JSON parsing (400 invalid_json).
3. Duplicate keys (400 duplicate_key), then the schema (422, with a code per rule).
4. The model name (404).
5. Field references, and label and level uniqueness ignoring case (422).
6. Rendering and token limits (413).
7. Idempotency (409).
8. Rate limits and quotas (429).
9. Balance (402).
10. Dispatch to a serving path (503 or 500).

Steps 1 to 9 never charge your balance.

When a body breaks several schema rules at once, the most specific code wins, in this order: unknown_field, field_not_allowed, missing_field, invalid_question_id, too_many_questions, too_many_options, invalid_levels, invalid_min_confidence, invalid_value, invalid_type. For a 422, param is a dotted path into the body, such as questions.spoed.instructions, or the name of a query parameter. For duplicate_key, param is a JSON pointer.

New codes can appear within v1 under an existing type. Act on the type, and treat an unknown code like the other codes of its type.

Retrying#

• 429, 503 and 409 idempotency_in_progress always carry a retry-after header in whole seconds, from 1 to 60. Wait that long, then retry. Two codes wait longer: test_daily_quota gives the time until 00:00 UTC, and the console's sign-in code limit gives the real wait, up to 3,600 seconds.
• 500 is safe to retry with the same idempotency key.
• 402 succeeds after you top up.
• Every other 4xx will fail again. Fix the request instead.
• Send an idempotency-key on POST /v1/decide so a retry can never charge twice. See Idempotency.
• Back off when there is no retry-after, for example after a network error. The SDKs retry 429 (but not test_daily_quota), 500, 502, 503, 504, 409 idempotency_in_progress, timeouts and network errors, with full-jitter exponential backoff from a 250 ms base, at most 3 retries.
• Watch for duplicate keys if you build JSON by hand or merge objects. A repeated key is a 400 duplicate_key, never silently the last value.

Refunds#

• Errors before admission (all 4xx) never charge. A 402 means nothing was charged.
• A request that fails with 500 or 503 after the charge is refunded in full before the response is sent. The tokens it took from your tokens-per-minute limit and, for a test key, from the daily test quota are given back too.
• A replay of a completed request with the same idempotency key is never charged. It returns the original response, including the original usage.

SDK error classes#

Until the SDKs are on PyPI and npm, install them from Downloads.

Each SDK raises one class per error type. The class comes from error.type in the body, or from the HTTP status when the body cannot be read.

All of these extend APIStatusError, which carries status, type, code, message, param, request_id, retry_after, idempotency_key and the response headers. An unknown type raises a plain APIStatusError, and so does a 405 method_not_allowed, which no SDK call can cause.

Errors without an HTTP answer have their own classes: APIConnectionError (with APITimeoutError under it), ResponseParseError for a body that is not valid JSON, and ConfigurationError, for example when no API key is set. The TypeScript SDK adds AbortedError when your AbortSignal stops a call. Every class extends DexError.

from thinqit_dex import RequestValidationError, InsufficientBalanceError

try:
    decision = client.decide(state=state, questions=questions)
except RequestValidationError as err:
    print(err.code, err.param, err.request_id)
except InsufficientBalanceError as err:
    print(err.required_micro_cents - err.balance_micro_cents, "micro-cents short")

import { RequestValidationError, InsufficientBalanceError } from "@thinqit/dex";

try {
  const decision = await client.decide({ state, questions });
} catch (err) {
  if (err instanceof RequestValidationError) {
    console.log(err.code, err.param);
  } else if (err instanceof InsufficientBalanceError) {
    console.log("Top up in the console:", err.message);
  } else {
    throw err;
  }
}

Getting help#

Every response and every error has a request id: req_ followed by 26 characters. Quote it when you contact support. Support asks for the request id, never for the content of your request.