Errors

Error format

The gateway returns errors in the dialect of the caller’s API surface.

OpenAI-compatible error envelope

{
  "error": {
    "message": "Invalid API key.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Anthropic-compatible error envelope

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key."
  }
}

Common errors

HTTP status	Cause	Resolution
401 Unauthorized	Invalid or missing API key	Check that you are passing a valid sk-ru-… key via Authorization: Bearer or x-api-key.
402 Payment Required	Insufficient balance	Top up your balance in the console → Billing.
400 Bad Request	Unknown model ID or malformed request	Verify the model ID against GET /v1/models. Check request body fields.
429 Too Many Requests	Rate limit exceeded	Reduce request frequency; implement exponential backoff.
502 Bad Gateway	Upstream provider error	Transient error from the upstream LLM provider. Retry with backoff.
503 Service Unavailable	Gateway overloaded or upstream unavailable	Retry with backoff.

Note

Errors are always returned with the appropriate HTTP status code and a JSON body in the caller’s dialect. When using an SDK (OpenAI or Anthropic), the SDK will raise the error as a native exception.

Retrying errors

For 502 and 503 errors, implement exponential backoff with jitter. For 402 errors, top up your balance before retrying — requests will continue to fail until the balance is positive.