Error response structure and common error types for the OpenAI-compatible API.
Error response
Business errors use this structure:
| Field | Type | Description |
|---|---|---|
error.type | string | Error category |
error.code | string | Machine-readable error code |
error.message | string | Error description; do not use it as a stable enum |
error.param | string / null | Parameter path; null for resource or system errors |
x-request-id in the header. Keep this value for troubleshooting. Successful resource bodies do not contain a uniform request_id field.
The order of fields in the error object is not fixed; read fields by name and do not rely on JSON order.
Common status codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix the request parameters as described |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
403 | Gateway error code | Confirm that the workspace exists and the current account has permission |
404 | not_found_error / not_found_error | Use a resource that exists and has not been deleted in the current workspace |
409 | conflict_error / conflict_error | Check the resource state, then retry with the same request body for the same idempotency key |
429 | Gateway error code | Reduce the request rate and retry |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |
502 | server_error / agents_api_upstream_unavailable | Retry later. If it keeps failing, submit a ticket with x-request-id |
503 | server_error / dependency-specific code | Retry later. If it keeps failing, submit a ticket with x-request-id |
Common param values
param uses a field path, for example:
modelenvironment.typeagent.tools[0].transport.typeevents[0].output
null.
Gateway errors
Authentication, workspace routing, rate limiting, and some routing errors can be returned directly by the gateway. Their structure may differ from business errors. Check the HTTP status, x-request-id header, and response body together; do not rely only on the message text.
Retry guidance
| Scenario | Recommendation |
|---|---|
429, 500, 502, 503 | Retry with exponential backoff; for write requests, confirm the idempotency key or resource state first |
409 | Retrieve the current resource state before retrying |
400, 401, 403, 404 | Fix the request or permissions; do not retry directly |
| SSE disconnect | Retrieve the session, turns, and items; do not rely on replay |