Errors

When the Syntic API cannot complete a request it answers with a non-200 HTTP status and a small JSON body. Branch on the error field: it is a stable, machine-readable code. Some errors add a human-readable detail or message, and a few add extra fields.

{
  "error": {
    "type": "authentication_error",
    "code": "revoked_api_key",
    "message": "This API key was revoked. Create a new one in Settings → API keys.",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d"
  }
}

Almost every response, including most errors, carries an x-syntic-request-id header. Log it next to the error; support can trace a request from that id. The two exceptions are 405 and 500: a 500 body carries a trace_id instead, which serves the same purpose.

Error shape at a glance

Error codes

400 Bad request

401 Unauthorized

402 Payment required

quota_exhausted means your plan allowance is used up and usage credits could not cover the request. The body explains which limit was reached and when it resets:

{
  "error": {
    "type": "insufficient_quota",
    "code": "quota_exhausted",
    "message": "You've hit your weekly usage limit. ...",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d",
    "limit": "weekly",
    "resets_at": "2026-10-13T12:00:00Z",
    "upgrade_url": "https://syntic.ai/pricing",
    "add_credit_url": "https://syntic.ai/agents/billing#api-topup"
  }
}

See Handle usage limits for a pattern that reacts to each case.

403 Forbidden

405, 413

429 Too many requests

You sent more than 600 requests in the last 60 seconds with the same key (or, for Syntic Code sign-ins, the same user). The window slides, so capacity frees up gradually rather than all at once.

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Retry shortly.",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d",
    "retry_after": 12,
    "retry_after_seconds": 12
  }
}

Detect it by error.type rate_limit_error (or the 429 status). Read the Retry-After header (seconds) first; the response also has X-RateLimit-Limit, X-RateLimit-Remaining (0) and X-RateLimit-Reset-Seconds. These headers are sent only on this 429, never on a successful response. See Limits.

5xx Server errors

Errors inside a stream

When a streamed reply fails after it has started, the status is already 200. Instead you receive a final event data: {"error":{"type":"api_error","code":"stream_error","message":"The response stream was interrupted. Retry the request.","param":null,"request_id":"req_6f1c2a9e0b7d4c3a8e5f1b2d"}} and the stream closes. See Streaming.

Errors in OpenAI-compatible SDKs

OpenAI-compatible client SDKs turn a non-200 response into an exception that holds the status code and the parsed body. Because Syntic’s error field is a string rather than an object, read the code from the raw body:

import openai
 
try:
    reply = client.chat.completions.create(model="Amara S1.2", stream=False, messages=messages)
except openai.APIStatusError as e:
    body = e.body if isinstance(e.body, dict) else {}
    code = (body.get("error") or {}).get("code")
    request_id = e.response.headers.get("x-syntic-request-id")
    print(e.status_code, code, request_id)

import OpenAI from 'openai'
 
try {
  const reply = await client.chat.completions.create({ model: 'Amara S1.2', stream: false, messages })
} catch (e) {
  if (e instanceof OpenAI.APIError) {
    const code = (e.error as { code?: string } | undefined)?.code
    const requestId = e.headers?.['x-syntic-request-id']
    console.error(e.status, code, requestId)
  } else {
    throw e
  }
}

The SDKs retry some failures (such as 429 and 5xx) a couple of times on their own. Set max_retries (Python) or maxRetries (Node.js) when you want to control this yourself.

Retrying safely

The full retry table, backoff timing and a helper are on Rate limits & retries.

• Retry 429 after the Retry-After delay, and 500, 502, 503 with exponential backoff (for example 1 s, 2 s, 4 s, with some random jitter). Stop after a few attempts.
• Do not retry other 4xx errors unchanged. Fix the request, the key or the account state first.
• Back off on 402 until resets_at, or until credits have been added.
• Retry upstream_error only when its status is 5xx; a 4xx there usually means the request itself was rejected (for example, it is longer than the context window).

A small helper that follows these rules:

import random, time
import openai
 
RETRYABLE = {429, 500, 502, 503}
 
def create_with_retry(client, attempts=4, **kwargs):
    for attempt in range(attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.APIStatusError as e:
            if e.status_code not in RETRYABLE or attempt == attempts - 1:
                raise
            wait = e.response.headers.get("retry-after")
            delay = float(wait) if wait else (2 ** attempt) + random.random()
            time.sleep(delay)

Tell support about a problem

Include the x-syntic-request-id (or trace_id for a 500), the time of the request, the model you asked for and the error code. Never include your API key.