Errors, limits, billing

Error format

The envelope matches OpenAI, so existing error handling needs no changes:

{
  "error": {
    "message": "Rate limit reached for requests. Limit: 60 requests/min.",
    "type": "rate_limit_exceeded",
    "param": null,
    "code": "rate_limited"
  }
}

Status codes

HTTP	type	What happened, and what to do
400	invalid_request_error	Bad parameter: a size the model does not accept, a file sent to a model that cannot read files. Check the catalog
400	content_filter	The upstream filter rejected the request. Rephrase the prompt
401	invalid_request_error	Key missing, revoked or wrong
402	insufficient_quota	Balance too low. Top up in your account
403	invalid_request_error	The key lacks the required scope
404	invalid_request_error	Model not found; the message lists similar identifiers
429	rate_limit_exceeded	Per-minute request limit exceeded
500	api_error	Our fault. Retry with exponential backoff
502	api_error	The upstream did not answer. Retry, or pick another model

Rate limit

The default is 60 requests per minute per key, over a rolling minute. Exceeding it returns 429 and two headers:

retry-after: 37
x-ratelimit-limit-requests: 60

retry-after is how many seconds to wait. The official OpenAI SDKs read it and back off on their own; a hand-rolled client should do the same.

The limit is per key, not per account — if you need more concurrency, spread the load across several keys.

Billing

• Charges come off your single Mixen balance, shared with the bot and the web account.
• You are charged on completion. A failed generation (failed, 502, a stalled video job) is not billed.
• The price is whatever the catalog shows at the time of the request. See Models and pricing for the formula and units.
• Chat spend appears in the response’s usage field; when streaming it arrives as a final chunk if you pass stream_options: {"include_usage": true}.

Retries

A reasonable production strategy:

1. 429 — wait out retry-after, then retry.
2. 500 and 502 — up to three attempts, waiting 1, 2, then 4 seconds.
3. 400, 401, 402, 403, 404 — do not retry. These are request or account problems; a retry returns the same answer and spends your limit.

Timeouts

Set your HTTP client timeout to at least 120 seconds for images and long chats: aborting on the client side does not cancel a generation already under way, and you will still be charged. Video and music need no timeout at all — they are asynchronous.