Errors

The Strata HTTP API returns errors as RFC 7807 problem documents. Every non-2xx response uses the same shape, so you can write one handler for the whole /v1/* surface.

Response shape

All errors return Content-Type: application/problem+json and a JSON body with these fields:

Some errors add extra fields for context — for example a 403 model_not_allowed includes requested_model and allowed_models, and a 429 includes retry_after, used, and limit. Treat any field beyond type/title/status as optional and tolerate its absence.

Tip

Branch on the type URI — match the stable slug after /errors/, not the HTTP status code or title. The title string may change; the type URI will not.

Error catalog

The type field is always the full URI https://api.strata.kronisys.com/errors/<slug>. The catalog lists the <slug> for readability.

Note

Token-budget exhaustion returns 429, not 403. The budget_exhausted body reports used (committed tokens since the cycle reset), in_flight (estimated tokens reserved by currently-running requests), and limit. Both the per-key budget and the shared organization token pool are enforced on the same call.

Examples

401 invalid_token

{
  "type": "https://api.strata.kronisys.com/errors/invalid_token",
  "title": "The provided API key is invalid, expired, or revoked.",
  "status": 401
}

403 model_not_allowed

{
  "type": "https://api.strata.kronisys.com/errors/model_not_allowed",
  "title": "Model \"claude-opus\" is not currently allowed by this organization's policy. Pick an allowed model or have an admin update the org's allowed models.",
  "status": 403,
  "requested_model": "claude-opus",
  "allowed_models": ["gpt-5.4", "gpt-5.4-mini", "claude-sonnet"]
}

429 rate_limit_exceeded

{
  "type": "https://api.strata.kronisys.com/errors/rate_limit_exceeded",
  "title": "API key rate limit exceeded (1000/1000 per hour). Retry after 42s.",
  "status": 429,
  "retry_after": 42,
  "used": 1000,
  "limit": 1000
}

A 429 rate-limit response also includes the Retry-After (seconds) and X-RateLimit-Reset (Unix epoch) headers, so you know exactly when to try again. Every successful response also carries X-RateLimit-Limit and X-RateLimit-Remaining.

Model governance and errors

The set of models a key may call is the intersection of your organization's allowed models, the key's allowed_models, and any role or per-user limits (including roles conferred by the actor's groups). Because your organization curates which models it enables from the central Model Catalog, a model that worked yesterday can return 403 model_not_allowed today if an admin disabled it — even if the key's own allowed_models still lists it. The organization's policy is always authoritative and is re-checked on every request. A request that names a retired model is checked as a request for its replacement, so a 403 model_not_allowed for it carries the replacement's id in requested_model, and a success carries a strata-model-retired header with the id you sent.

Separate from that allow-list, the org may cap how much of a given model each actor may use. When the requested model's allowance is exhausted, one of two things happens:

• If no fallback is configured, the call returns 429 model_allowance_exhausted with requested_model and a Retry-After.
• If the org configured a cheaper fallback model, the call succeeds on the fallback rather than failing. The response's model field names the model that actually ran, and a strata-model-fallback response header names the model you asked for. Read both when you need to know exactly which model produced a reply.

Tip

Don't hard-code model IDs in retry logic. On a 403 model_not_allowed, read allowed_models from the response body and fall back to one of those, or surface the error to whoever provisioned the key.

How to handle errors

Build one error handler that reads type and decides what to do.

Retry on 5xx and 503

500, 503 budget_check_failed, 503 entitlement_check_failed, and 503 policy_lookup_failed are transient. Retry with exponential backoff (for example: 1s, 2s, 4s, 8s, cap at 30s) and a small amount of jitter. Cap total retries at 3–5 attempts.

Key

On the non-streaming POST /v1/chat, send an Idempotency-Key header on retries. Strata caches the first result for 24 hours and replays it on a repeat with the same key, so a network-timeout retry never creates a duplicate conversation or double-bills. While the first request is still running, a retry returns 409 request_in_progress — wait, then retry to fetch the cached result. Idempotency is not applied to streaming requests; streaming clients recover by reconnecting, not re-POSTing.

Back off on 429

When you receive a 429, wait for the duration in Retry-After (or until the timestamp in X-RateLimit-Reset) before sending another request with the same key. A budget_exhausted 429 will not clear until the organization's billing cycle resets, so back off long rather than retry tightly. Spreading bursts across multiple keys is fine; hammering a throttled key is not.

Don't retry most 4xx

400, 401, 402, 403, 404, 413, and 422 will never succeed on retry without changing the request. Surface them to your caller or your logs, fix the underlying cause (bad payload, missing scope, disallowed model, expired key, rejected spec), then send a new request. The exception is 409 request_in_progress, which clears once the in-flight request completes.

Log the request context

Log the type, title, and any extra fields (such as allowed_models or required_scope) on every failure. Include them in any support request — they let the Kronisys Inc. team trace the exact problem without asking you to reproduce it.

Related

• Authentication
• Rate limits and budgets
• API overview
• Models