Status Code Mapping
Chuizi.AI acts as a gateway between your application and upstream AI providers. When a provider returns an error, the gateway maps it to a consistent, OpenAI-compatible error format. This page documents how upstream errors are translated.
Mapping Principle
All upstream errors are normalized to the Chuizi.AI error format. Your application only needs to handle one error schema regardless of which provider processes the request.
Upstream Provider Error → Chuizi.AI Gateway → OpenAI-Compatible Error Response
The original provider error details are logged server-side with the X-Request-Id for debugging but are never exposed to the client.
General Mapping Rules
| Upstream Status | Gateway Status | Error Code | Error Type | Description |
|---|---|---|---|---|
| 400 | 400 | bad_request | invalid_request_error | Provider rejected the request as malformed. |
| 401 | 502 | provider_error | upstream_error | Upstream auth failure (gateway key issue, not your key). |
| 403 | 502 | provider_error | upstream_error | Upstream permission denied (gateway account issue). |
| 404 | 404 | model_not_found | not_found | Model does not exist at the upstream provider. |
| 429 | 429 | rate_limit_exceeded | rate_limit_error | Upstream provider rate limit hit. Gateway returns Retry-After. |
| 500 | 502 | provider_error | upstream_error | Upstream internal error. |
| 502 | 502 | provider_error | upstream_error | Upstream bad gateway. |
| 503 | 503 | provider_unavailable | service_unavailable | Upstream service is down or overloaded. |
| 504 | 504 | provider_timeout | timeout_error | Upstream did not respond in time. |
| Connection refused | 503 | provider_unavailable | service_unavailable | Upstream host is unreachable. |
| DNS failure | 503 | provider_unavailable | service_unavailable | Upstream hostname cannot be resolved. |
| TLS error | 503 | provider_unavailable | service_unavailable | TLS handshake with upstream failed. |
| Request timeout | 504 | provider_timeout | timeout_error | Gateway's own timeout exceeded waiting for upstream. |
Next Steps
- Error Codes — Full error code reference with troubleshooting guidance
- Provider-Specific Behavior — Content filters, token limits, and streaming differences by provider
- Circuit Breaker — How the gateway detects and routes around unhealthy providers