Errors and retries | Synux Docs

Check the HTTP status, response body, and X-Request-Id together. The request ID lets Synux trace a failure without requiring you to share an API key or full request body.

Gateway error shape

Errors generated by the Synux gateway use an OpenAI-style envelope:

{
  "error": {
    "message": "The model service is temporarily unavailable.",
    "type": "api_error",
    "param": null,
    "code": "upstream_unavailable"
  }
}

A model provider may add compatible fields or return a more specific error. Clients should tolerate unknown fields.

Common HTTP statuses

Status	Meaning	What to check
`400`	Invalid request	JSON syntax, required fields, and model capabilities
`401`	Authentication failed	Missing, malformed, disabled, expired, or revoked API key
`404`	Route or model not found	Base URL, endpoint path, and exact model ID
`429`	Request was rate limited	Concurrency, request rate, and model availability
`500`	Gateway could not process the request	Capture the request ID and retry only when safe
`503`	Model service is temporarily unavailable	Retry with backoff or choose another available model

An insufficient account balance or per-key spending limit can also prevent a request. Check Billing and the key’s remaining quota in the Dashboard.

Retry safely

Retry 429, 500, and 503 responses only when the operation can tolerate a duplicate attempt. Use exponential backoff with jitter and a fixed maximum:

const delayMs = Math.min(8_000, 500 * 2 ** attempt);
const jitterMs = Math.random() * 250;
await new Promise((resolve) => setTimeout(resolve, delayMs + jitterMs));

Recommended behavior:

Cap both attempts and total elapsed time.
Respect Retry-After when the response supplies it.
Stop immediately on authentication or validation errors.
Do not blindly replay a streaming request after output begins.
Avoid synchronized retries across workers; always add jitter.

Report an issue

Provide:

The X-Request-Id response header
The approximate request time and timezone
The endpoint and model ID
The HTTP status and sanitized error code

Never send the API key, Authorization header, complete prompt, or sensitive model output in a support request.