Error Codes
| HTTP | Description |
|---|---|
| 400 | Bad Request - Your request is invalid. |
| 401 | Unauthorized - Your API key is wrong. |
| 403 | The user or project is not permitted to perform this request. |
| 402 | ZeroClave account or project quota is insufficient. Check your plan and credits. |
| 404 | Not Found - The requested resource does not exist. |
| 413 | Request body exceeds the allowed size; reduce the request. |
| 429 | ZeroClave caller rate limit reached. Reduce frequency and respect Retry-After when available. |
| 500 | Internal service error (internal_error). Try again later. |
| 502 | Model temporarily unavailable (model_unavailable); the call did not complete normally. |
| 503 | Inspect error.code: model_unavailable means temporary model unavailability; pii_mapping_saturated means privacy-processing capacity is full and requires administrator or support assistance. |
| 504 | Model call timed out (model_unavailable). Check the outcome before retrying. |
{"error":{"message":"模型暂时不可用，请稍后重试","type":"server_error","code":"model_unavailable"}}Privacy-processing capacity
For HTTP 503 with error.type: "server_error" and error.code: "pii_mapping_saturated", stop automatic retries and contact your project administrator or platform support with the response X-Request-ID. Repeated submissions usually do not resolve this condition. Do not infer retryability from HTTP 503 alone.
{"error":{"message":"当前隐私保护处理容量达到上限，请联系项目管理员或平台支持并提供请求编号；重复提交通常无效。","type":"server_error","code":"pii_mapping_saturated"}}The example preserves the current API message; use the stable error.code for programmatic handling rather than matching message text. This error does not include Retry-After. The console also ignores that header if it is mistakenly supplied with this code.
Retry-After response header
Retry-After is an HTTP response header, not a field in the JSON error body. For example, Retry-After: 30 advises waiting 30 seconds before retrying. It does not trigger retries or guarantee recovery. Ordinary caller rate limits can still return HTTP 429 with this header.
The console reads the header and converts it to its local ApiError.retryAfterSeconds property; that property is not part of the API response body. The parser accepts integer seconds or an HTTP date and ignores invalid values or delays exceeding 24 hours.
For support, record the response X-Request-ID, time and error code. X-Request-ID is a client correlation identifier and is not guaranteed globally unique. Never include keys or sensitive request bodies.