API documentation
Errors
Error response shape, common status codes, causes, and fixes.
Errors are returned in an OpenAI-compatible shape. The message usually contains a short explanation.
Shape
json
{ "error": { "message": "No available channel for model openai/unknown-model", "type": "api_error", "param": null, "code": "model_not_found", "status": 503 }}Common status codes
| Status | Type/code | Cause | Fix |
|---|---|---|---|
| 400 | invalid_request_error | Bad JSON, wrong endpoint, unsupported parameter, invalid image size. | Check the body and remove optional fields. |
| 401 | authentication_error | Missing or invalid key. | Check Authorization: Bearer ... |
| 402 | insufficient_quota | Not enough balance/quota. | Top up or reduce the request. |
| 403 | permission_error | No model access or Telegram verification required. | Check model id and account status. |
| 404 | not_found | Wrong path or model id. | Verify endpoint and exact id. |
| 413 | context_length_exceeded | Input/context too large. | Reduce messages or use a larger-context model. |
| 429 | rate_limit_error | RPM/TPM/concurrency limit. | Wait, reduce concurrency, add backoff. |
| 500 | api_error | Internal error or unexpected provider response. | Retry later. |
| 502 | api_error | Upstream temporarily unavailable or overloaded. | Retry with backoff or choose another model. |
| 503 | api_error | No available channel for the model. | Check model id or retry later. |
Image errors
- GPT Image: use /v1/images/generations for generation and /v1/images/edits for editing; read data[0].b64_json or data[0].url.
- Gemini image models: use /v1/chat/completions, include modalities, and read choices[0].message.images.
- If Gemini image model content is null, that is normal; inspect message.images.
- If an image does not decode, check the data:image/...;base64 prefix and decode the part after the comma.
Server overload
Overload details are hidden behind a normal 502 Service temporarily unavailable response so internal service details are not exposed.