API reference

Errors

Errors return a non-2xx status and a JSON body. The shape matches OpenAI's, so OpenAI SDKs raise them as normal exceptions.

Error shape

json

{
  "error": {
    "code": "insufficient_balance",
    "type": "insufficient_quota",
    "message": "Your balance is too low for this request. Top up in the console.",
    "request_id": "6f1d2c9e-4b7a-4f0e-9a51-0c2e8b3d7a11"
  }
}

code is stable and safe to branch on. message is for people and may change. request_id matches the x-request-id response header.

Error codes

Errors
Code	HTTP	What happened	Retry?	What to do
`unauthorized`	`401`	The API key is missing, wrong, disabled or revoked.	No	Check the key and the `Authorization: Bearer` header.
`validation_error`	`400`	The body isn't valid JSON or a field is wrong.	No	Read the message, which names the field, and fix the request.
`content_policy`	`400`	The request was refused.	No	Change the request. You weren't charged.
`insufficient_balance`	`402`	Your balance can't cover the request.	No	Top up on the Billing page.
`not_found`	`404`	The job doesn't exist or belongs to another account.	No	Check the job id and that you're using the right key.
`rate_limited`	`429`	Too many requests, or the model is briefly busy.	After `Retry-After`	Wait for `Retry-After`, then retry. Ask us for a higher limit if it happens often.
`capacity_full`	`503`	Image or video generation is at full capacity.	No	Contact us to join the waitlist.
`generation_failed`	`502`	The model couldn't produce a reply.	Yes, with backoff	Retry with backoff. You weren't charged.
`internal`	`500`	Something went wrong on our side.	Yes, with backoff	Retry with backoff. If it keeps happening, contact us with the `request_id`.

Retry safely

OpenAI SDKs retry 429 and server errors automatically and wait for Retry-After. Set a retry count and timeout, or add a small retry loop if you call the API directly:

python

client = OpenAI(
    base_url="https://api.sweetrouter.com/v1",
    api_key=os.environ["SWEETROUTER_API_KEY"],
    max_retries=3,   # retries 429 and 5xx with backoff, honours Retry-After
    timeout=60,      # seconds
)

Request ids

Every response has an x-request-id header. Include it when you contact us and we can find the exact call.