Errors

Errors always use one JSON shape.

Error JSON

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be a JSON object",
    "status": 400,
    "metadata": {
      "request_id": "..."
    }
  }
}

Code and cause

Error	Meaning
400 invalid_request	invalid JSON, missing model, unsupported parameter, or mixed free and paid fallback models.
401 invalid_api_key	missing or invalid key.
402 insufficient_balance	account balance is too low.
403 telegram_link_required	link Telegram on /settings before using a free model.
429 rate_limited	a request limit is exhausted; for the free-model daily limit metadata.limit_type is free_models_daily_requests and Retry-After is seconds until UTC midnight.
429 rate_limited	for models sponsored by a Happy Hour promotion, metadata.limit_type is happy_hour_requests_per_minute and a separate per-user minute limit applies.
503 no_available_provider	no route is currently available for the selected model and endpoint.
503 service_unavailable	free-model access checks are temporarily unavailable and the request is rejected before any provider call.
409 `max_cost_exceeded`	The quote exceeds `max_cost_usd`. Obtain a new quote and review the amount before generating.
422 `max_price_no_route`	No route matches the price limits. Check `max_price` and rates; no paid call was made.

Contact support

metadata.request_id is useful when contacting support.