Error codes

Every error from /v1 comes back in one shape, the error envelope, whichever check refused the request. This page describes that shape and lists every code POST /v1/chat/completions and GET /v1/models can return today, with its HTTP status, the situation that causes it, and whether a retry can help. For advice on handling errors inside an application, see Errors.

The error envelope

{
  "error": {
    "type": "insufficient_quota",
    "code": "quota_exhausted",
    "message": "Your monthly plan token allowance is used up. ...",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d",
    "limit": "monthly",
    "resets_at": "2026-11-01T00:00:00.000Z",
    "upgrade_url": "https://syntic.ai/pricing",
    "add_credit_url": "https://syntic.ai/agents/billing#api-topup"
  }
}

The shape is OpenAI-compatible, so client libraries that read error.type, error.code and error.message work unchanged.

Error responses carry Cache-Control: no-store. Messages never contain text from the model service: no vendor names, hosts, internal model ids or raw error bodies. When the original message cannot be shown, the code’s standard sentence is used instead.

Types

Any other status from inside the platform is folded into one of these before it reaches you: an unlisted 4xx becomes 400, and an unlisted 5xx becomes 502 (503 for an overloaded service).

Status codes at a glance

This table is generated from the public error catalog in the platform’s error envelope (supabase/functions/api-proxy/error-envelope.ts on develop). type is fixed by the HTTP status; code is the machine-readable reason. stream_error arrives inside a stream that already answered 200. model_not_found and model_not_in_plan are in the catalog on develop but not returned in production yet.

Not in the public catalog (provisional). The platform also returns model_unavailable (400), zero_retention_unavailable (403), feature_unavailable (403) and model_retention_unverifiable (503) today, and Syntic Desktop sign-ins can see org_required, quota_exceeded, prompt_too_large, concurrent_request and temporarily_unavailable. These keep the envelope and the type for their status, but are not catalog codes yet and may be renamed or folded into one. Handle them by type.

400 Bad Request

401 Unauthorized

402 Payment Required

quota_exhausted means the request cannot be paid for. The limit field says which cap stopped it:

Extra fields: limit, resets_at (ISO 8601 time, or null), upgrade_url, add_credit_url. When usage cannot be checked at all, the answer is 503 usage_check_unavailable instead (see 5xx). See Handle usage limits.

quota_exceeded (Desktop) means the Free plan’s monthly tokens are used up. Extra field: action_url, the upgrade page.

403 Forbidden

More on credential errors is in Authentication.

404 Not Found

model_not_found: model is not a model id that GET /v1/models returns for this credential, or GET /v1/models/{id} names a model that is unknown or that this credential cannot use. Names are exact and case-sensitive. Internal engine ids are treated as unknown names. Do not retry; list the models first.

Not live yet — on develop. Production does not return model_not_found yet: today POST /v1/chat/completions answers an unknown name with the default model instead.

405 Method Not Allowed

Do not retry; fix the method or the path.

413 Payload Too Large

Do not retry unchanged. Trim older turns, summarise long history, or move large documents out of the prompt.

429 Too Many Requests

Every 429 carries a Retry-After header and error.retry_after. Wait at least that long.

5xx Server errors

Errors inside a stream

When a streamed response has already started with 200 OK and then breaks, the last event carries the envelope with code: "stream_error" and type: "api_error", then the stream ends:

data: {"error":{"type":"api_error","code":"stream_error","message":"The response stream was interrupted. Retry the request.","param":null,"request_id":"req_6f1c2a9e0b7d4c3a8e5f1b2d"}}

Text already received may be incomplete. Retry the whole request. See Stream format.

Handling errors

curl -sS https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Amara Deep", "messages": []}' \
  | jq '.error.type, .error.code, .error.request_id'

const RETRY = new Set(['rate_limit_error', 'service_unavailable_error', 'api_error', 'timeout_error'])
 
async function call(body, attempt = 0) {
  const res = await fetch('https://app.syntic.ai/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  })
  if (res.ok) return res.json()
  const { error } = await res.json()
  if (RETRY.has(error.type) && attempt < 4) {
    const wait = error.retry_after ?? 2 ** attempt
    await new Promise((r) => setTimeout(r, wait * 1000 + Math.random() * 250))
    return call(body, attempt + 1)
  }
  throw new Error(`${error.type}/${error.code} (${error.request_id}): ${error.message}`)
}

import os, random, time, requests
 
RETRY = {"rate_limit_error", "service_unavailable_error", "api_error", "timeout_error"}
 
def call(body, attempt=0):
    r = requests.post(
        "https://app.syntic.ai/v1/chat/completions",
        headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
        json=body,
        timeout=600,
    )
    if r.ok:
        return r.json()
    e = r.json()["error"]
    if e["type"] in RETRY and attempt < 4:
        wait = e.get("retry_after") or 2 ** attempt
        time.sleep(wait + random.random() / 4)
        return call(body, attempt + 1)
    raise RuntimeError(f"{e['type']}/{e['code']} ({e.get('request_id')}): {e['message']}")

Retrying safely

1. Retry only the types rate_limit_error, service_unavailable_error, api_error and timeout_error, plus feature_unavailable after a pause, and a broken stream.
2. On 429 and 503, wait at least Retry-After seconds.
3. Otherwise back off exponentially with jitter (about 1 s, 2 s, 4 s, capped near 30 s) and stop after a few attempts.
4. A 4xx other than 429 fails the same way when sent again unchanged.

Each retried request that produces output is billed on its own.

Codes planned for new endpoints

Endpoint pages list the codes specific to them.

Related pages

• Request IDs
• Rate-limit headers
• Sign in with Syntic: OAuth error codes
• Errors: handling advice