Account

Errors

Errors come back as JSON with a readable message and a standard HTTP status.

Error shape

json

{
  "error": {
    "message": "Insufficient balance. Top up at /app/wallet."
  }
}

message is always present and safe to show to a developer. code is included when the error came from the model provider.

Status codes

Status	Meaning	What to do
`400`	The request is malformed: missing `model` or `messages`, or invalid JSON.	Fix the body. Do not retry unchanged.
`401`	The API key is missing, wrong or revoked.	Check the header and the key on API keys.
`402`	Balance below $0.02 for a paid model.	Top up, or use a `:free` model.
`404`	The model ID is not available.	Copy an ID from `GET /models`.
`429`	A rate limit, the free-model quota, or the key's daily spending limit was reached.	Back off and retry, or raise the key's limit. See Rate limits.
`500`	Something failed on Synaps. The body may not be JSON.	Retry once. If it persists, contact us with the time of the request.
`502` / `503`	The model provider is down, overloaded, or Synaps is temporarily unavailable.	Retry after a few seconds, or switch models.
Other `4xx`	Passed through from the provider, for example a context window exceeded or content refused.	Read `message`; shorten the input or change the request.

Which errors cost money

Errors returned before the model produced output are free. A stream that fails partway is charged for the tokens the provider generated up to that point.

Handling errors with the OpenAI SDK

python

from openai import APIStatusError, AuthenticationError, RateLimitError

try:
    reply = client.chat.completions.create(model="deepseek/deepseek-chat", messages=messages)
except AuthenticationError:
    print("Bad or revoked key")
except RateLimitError as e:
    print("Slow down:", e.message)
except APIStatusError as e:
    if e.status_code == 402:
        print("Top up your Synaps balance")
    else:
        print(e.status_code, e.message)