Error Codes
ZBStream uses standard HTTP status codes. Error responses usually carry a readable message; clients should log the request time, model, and status code.
What should I do about 429 / 5xx errors?
| Code | Meaning | Suggested action |
|---|---|---|
| 400 | Invalid parameters or message format | Check the JSON body, model, and messages |
| 401 | API key missing, invalid, or revoked | Check the Authorization header |
| 402 | Insufficient credit balance | Top up credits and retry |
| 403 | API key not authorized for this model | Check the key's model scope |
| 404 | Route not found | Check the base URL and path; verify the model via /v1/models |
| 429 | Upstream provider rate limit | Retry with exponential backoff |
| 500 | Internal server error | Keep the request details and retry later |
| 502 | Failed to connect to or read the model service | Retry later or check channel configuration |
| 503 | Service not configured or temporarily unavailable | Retry later or check service status |
| 504 | Upstream gateway timeout | Retry later or switch channels |
Retry Policy
- Retry only 429, 502, 503, 504, and network interruptions, with a bounded number of attempts.
- Never auto-retry parameter errors, authentication errors, or insufficient balance.
- Keep your own request idempotency keys for non-idempotent operations to avoid double processing.