REST API

Errors & retries

HTTP status codes, error shapes, and recommended retry behavior.

Classifier application errors use standard HTTP status codes and a consistent JSON body. Successful classifications always return 200.

Error shape#

Application-generated classifier errors carry a JSON object with a detail string. CDN-generated edge failures may use a different response shape.

JSON

{ "detail": "Valid API key required. Pass Authorization: Bearer tsk_..." }

Status codes#

Status	Meaning	Retry?
`200`	Success.	n/a
`401`	Missing, malformed, or unknown API key.	No. Fix the key.
`413`	Request body exceeds the configured limit (10 MiB by default).	No. Reduce the payload.
`422`	Invalid request body (empty text, wrong field type).	No. Fix the request.
`500 / 503`	Transient service error.	Yes, with backoff.
`502 / 504`	Upstream or edge failure, including the gateway response-start deadline.	Yes, with backoff.

Retrying#

Classification does not mutate policy or application resources, so retrying the operation is safe. A retry after response loss can create a duplicate telemetry event because checks do not carry an idempotency key. Retry 500, 502, 503, and 504 with exponential backoff and jitter. Do not retry 401, 413, or 422. The service does not currently rate-limit with 429; the official SDKs nevertheless treat 429 as retryable for forward compatibility and implement this backoff policy for you (default 2 retries).

Text

attempt 1 -> 503
wait ~0.25s (+ jitter)
attempt 2 -> 503
wait ~0.5s (+ jitter)
attempt 3 -> 200

Fail closed#

When a check cannot complete after retries, decide deliberately. Treating classifier unavailability as unsafe (fail closed) keeps an outage from silently disabling your runtime controls. The SDKs raise a typed error you can catch:

try:
    verdict = triage_sdk.input.check(user_text)
    allowed = verdict.is_safe
except triage_sdk.TriageError:
    allowed = False  # fail closed: treat unavailability as unsafe