Errors and limits

Errors come back OpenAI-shaped, so existing SDK error handling works unchanged:

{
  "error": {
    "message": "human-readable explanation",
    "type": "invalid_request_error | api_error | ...",
    "code": "machine_readable_code"
  }
}

Handle on code rather than on the message: the codes below are stable, the wording is not.

Status codes

• 400 - invalid request. On chat: invalid_json, missing_model, unknown_model and model_not_hosted. On speech: invalid_request_error, missing_model, missing_input, invalid_input, unknown_model, input_too_long and unsupported_response_format. On transcription: an upload that could not be parsed or a missing file field. DevThrottle never silently substitutes a different model; fix the id against GET /models.
• 401 - invalid_api_key: missing, malformed, or revoked API key. See authentication.
• 402 - the request was not run, and nothing was debited. Four codes, and they need different fixes:
  • insufficient_credits - a direct catalog-model call with an empty credit balance. Top up.
  • monthly_limit_reached - your own monthly spending limit. Raise it in Billing.
  • subscription_required - an included service called by an account with no active subscription or trial. Fixed by an active Pro subscription or trial, not by credits.
  • fair_use_limit_reached - the monthly fair-use limit on included AI features. It resets at the start of the next month; credits do not lift it.
  Dictation, spoken replies, and the wingman never cost credits - a declined included service is an entitlement outcome, never a balance one.
• 404 - not_found: an address the API does not serve, including the right path with the wrong method on /chat/completions and the /audio/* endpoints, which are POST only.
• 405 - method_not_allowed: sent by GET /models for any other verb.
• 413 - payload_too_large: audio over the 4 MB per-request limit on transcription.
• 429 - rate_limit_exceeded, with "type": "rate_limit_error": the per-account burst limit on chat completions. Slow down and retry.
• 500 - internal_error (or config_error): something is wrong on our side, not in your request.
• 502 - upstream_error: the model service failed or could not be reached.
• 504 - upstream_unavailable or upstream_timeout on transcription: the speech service was unreachable, or did not answer in time. No request was billed.

One shape to expect beyond that list: when the model service itself rejects a chat or speech request, its status passes through to you - so a client should treat any non-2xx as an error rather than switching only on the codes above. A failed request is never debited, whichever status it carries.

Rate limits

A burst limit is enforced per account on chat completions and returns 429. There is no published per-account quota yet - when one is published it will appear here. Until then, write clients the way you would for any rate-limited API: handle non-200s, back off on 429 and 5xx, and do not hot-loop retries.

The included AI services - transcription and speech - are bounded differently: not by a request rate but by a monthly fair-use limit, which answers 402 fair_use_limit_reached and resets at the start of the next month. Retrying does not clear it.