Skip to main content

Errors

Error response structure and common error types for the OpenAI-compatible API.

Error response

Business errors use this structure:
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "$: required property 'model' not found",
    "param": "model"
  }
}
FieldTypeDescription
error.typestringError category
error.codestringMachine-readable error code
error.messagestringError description; do not use it as a stable enum
error.paramstring / nullParameter path; null for resource or system errors
Responses include 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 statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix the request parameters as described
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
403Gateway error codeConfirm that the workspace exists and the current account has permission
404not_found_error / not_found_errorUse a resource that exists and has not been deleted in the current workspace
409conflict_error / conflict_errorCheck the resource state, then retry with the same request body for the same idempotency key
429Gateway error codeReduce the request rate and retry
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id
502server_error / agents_api_upstream_unavailableRetry later. If it keeps failing, submit a ticket with x-request-id
503server_error / dependency-specific codeRetry later. If it keeps failing, submit a ticket with x-request-id

Common param values

param uses a field path, for example:
  • model
  • environment.type
  • agent.tools[0].transport.type
  • events[0].output
Cross-field constraints, missing resources, and system errors can return 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

ScenarioRecommendation
429, 500, 502, 503Retry with exponential backoff; for write requests, confirm the idempotency key or resource state first
409Retrieve the current resource state before retrying
400, 401, 403, 404Fix the request or permissions; do not retry directly
SSE disconnectRetrieve the session, turns, and items; do not rely on replay