Error Handling
All capabilities exposed by the open platform adhere to a unified response and error structure specification.
1. Response Structure Specification
1.1 Success Response (HTTP 200)
{
"code": 200,
"message": "success",
"data": { ... }
}code: Always200on successful business processing.message: Always"success".data: Business payload object or array.
1.2 Error Response (HTTP 200)
To simplify error-handling across client applications and SDKs, all open platform API endpoints uniformly return HTTP 200 OK as long as network transport is connected. The actual business result is determined solely by the code field in the response envelope. When a failure occurs, the response includes code, error_code, message, data: null, and a unified trace identifier call_id:
{
"code": 10002,
"error_code": "INVALID_API_KEY",
"message": "The API key is invalid or has expired",
"data": null,
"call_id": "call_94b5952f4dc248dbb4f6236bb5ff64cf"
}Field definitions:
| Field | Type | Description |
|---|---|---|
code | integer | Unified numeric status code. Always 200 on success; 5-digit business error code on failure (e.g. 10002) |
error_code | string | Machine-readable uppercase string constant (e.g. INVALID_API_KEY) for programmatic branch logic |
message | string | User-friendly error message description |
data | null | Always null on failure |
call_id | string | Unique request tracking ID (starting with call_), matching X-QJ-Request-ID in response headers for troubleshooting and technical support |
Recommendation
Clients and SDKs should determine success by checking res.code === 200. Network request libraries will not reject or throw HTTP errors on API business failures, simplifying invocation workflows. Match against error_code for specific error handling.
2. Business Error Code Ranges and Codes
Platform error codes are structured across 5 core functional domains:
| Range | Domain | HTTP Mapping | Primary Scenarios |
|---|---|---|---|
| 200 | Success | 200 | Request completed normally |
| 10000 ~ 19999 | Auth & Permissions | 401 / 403 | Missing credentials, invalid API key, expired token, forbidden capability |
| 20000 ~ 29999 | Request & Params | 400 / 415 / 422 | Malformed JSON, validation failure, unsupported media type, not found |
| 30000 ~ 39999 | Billing & Quotas | 402 / 429 | Quota exhausted, insufficient balance, rate limit exceeded |
| 50000 ~ 59999 | Service & Maintenance | 500 / 502 / 503 / 504 | Service busy, please retry later |
Common Error Codes Reference
code | error_code | HTTP Status | Description & Recommended Action |
|---|---|---|---|
10001 | UNAUTHORIZED | 401 | Missing authentication credentials (Authorization or x-api-key) |
10002 | INVALID_API_KEY | 401 / 403 | API key is invalid or deactivated |
10003 | TOKEN_EXPIRED | 401 | Access token expired; exchange for a new token |
10004 | TOKEN_REVOKED | 401 | Token was explicitly revoked |
10005 | INSUFFICIENT_SCOPE | 403 | API key lacks permission to call this capability |
10006 | CAPABILITY_FORBIDDEN | 403 | Capability not enabled for current project |
10007 | USER_DISABLED | 403 | User account has been deactivated |
10008 | PROJECT_DISABLED | 403 | Project is deactivated |
10009 | CLIENT_TOKEN_REQUIRED | 401 | Client-side call requires a valid client token |
20001 | INVALID_REQUEST | 400 | Request body or parameters are invalid |
20002 | VALIDATION_ERROR | 422 | Request validation failed (missing required field, value out of range) |
20003 | UNSUPPORTED_MEDIA_TYPE | 415 | Unsupported media type (e.g. file upload not using multipart/form-data) |
20004 | REQUEST_BODY_TOO_LARGE | 413 | Request body exceeds maximum allowed size |
20005 | RESOURCE_NOT_FOUND | 404 | Route, task, file, or resource entity not found |
20006 | IDEMPOTENCY_CONFLICT | 409 | Conflicting request with the same idempotency key |
30001 | QUOTA_EXHAUSTED | 402 / 403 | Free quota has been exhausted |
30002 | INSUFFICIENT_BALANCE | 402 | Account wallet balance insufficient for invocation |
30003 | RATE_LIMIT_EXCEEDED | 429 | Rate limit or concurrency limit exceeded; retry with exponential backoff |
50001 | SERVICE_BUSY | 500 / 502 / 503 / 504 | Service busy, please retry later; if persistent, retain X-Request-ID and contact support |
3. SSE error event
Streaming endpoints (reason-info, if-continue-ask, summary, ai-pic/summary/stream) report failure as a terminal event:
data: {"type":"error","code":"AI_DOC_CONTINUE_STREAM_FAILED","error_code":5401,"message":"流式判断是否继续追问失败","retryable":true,"recommended_action":"retry_later"}| Event type | Description | Data format |
|---|---|---|
error | Terminal failure event of a streaming endpoint; retry only when retryable is true, with a bounded retry budget | {"type":"error","code":"<INTERNAL_CODE>","error_code":<PUBLIC_CODE>,"message":"failure reason","retryable":true,"recommended_action":"retry_later"} |
On error, or when the connection closes before completion, do not continue to the next step. error_code values are listed under task-level error codes.
4. Task-level error codes
When an asynchronous task fails, the HTTP status is still 200 and code is still 200; the public numeric error code appears only inside the task object:
{
"code": 200,
"message": "success",
"data": {
"task_id": "<TASK_ID>",
"status": "failed",
"error_code": 5105
}
}- Detect failure from
data.status(failed/canceled), not from the HTTP status orcode. data.error_code: the public numeric code when the task failed;nullotherwise.- The envelope has only
code,messageanddata— there is no top-levelerror_code; you must parsedatato detect task failure.
Read it with GET /ai-tasks/{task_id}. The task object no longer returns the internal reason key, an error message, retryable, or recommended_action; decide retryability from the table below (the published platform contract).
error_code | Meaning | retryable | recommended_action |
|---|---|---|---|
4001 | Invalid request parameters or business input | false | correct_request |
4002 | Missing or invalid credentials | false | sign_in |
4003 | Not permitted to perform this operation | false | go_back |
4004 | Requested resource does not exist | false | go_back |
4005 | Submitted content exceeds the size limit | false | reduce_file_size |
4101 | The image is not suitable for this recognition | false | replace_image |
4102 | Select an image before recognition | false | replace_image |
4103 | Image is too large | false | reduce_file_size |
4104 | Unsupported image format | false | replace_image |
4105 | Empty or invalid image file | false | reupload_media |
4106 | Invalid image address | false | reupload_media |
4107 | Unsupported image source | false | reupload_media |
4108 | Image temporarily unreachable | true | retry_later |
4501 | Unsupported media format or type | false | reupload_media |
4502 | This media cannot be used for the current business | false | reupload_media |
4503 | Media integrity check failed | false | reupload_media |
4504 | Media file exceeds the size limit | false | reduce_file_size |
4505 | Media file is empty or unreadable | false | reupload_media |
5001 | Service temporarily unavailable | true | retry_later |
5002 | Service busy | true | retry_later |
5003 | Task submission failed | true | retry_later |
5004 | Dependent service temporarily unavailable | true | retry_later |
5101 | Image-recognition service timed out | true | retry_later |
5102 | Image-recognition service temporarily unavailable | true | retry_later |
5103 | Image-recognition configuration unavailable | true | retry_later |
5104 | Image-recognition result generation failed | true | retry_later |
5105 | Image report generation incomplete | true | retry_later |
5106 | Image-recognition connection interrupted | true | retry_later |
5401 | Smart Consultation connection interrupted | true | retry_later |
5501 | Media storage temporarily unavailable | true | retry_later |
5502 | Media processing temporarily unavailable | true | retry_later |
5503 | Invalid media processing result | true | retry_later |
6001 | Request conflicts with an existing task | false | use_existing_task |
6002 | Current task state does not allow this operation | false | refresh_state |
6003 | Task canceled | false | refresh_state |
6004 | Task expired | false | refresh_state |
6101 | Image is being analysed | true | wait_and_poll |
6102 | Image report task already submitted | false | use_existing_task |
6103 | Image-recognition type does not match this session | false | restart_session |
6106 | Session language does not match | false | restart_session |
6501 | Media file not ready yet | true | wait_and_poll |
6502 | Media file does not match the current task | false | reupload_media |
6503 | Media processing stage not eligible | true | wait_and_poll |
When retryable is true, retry with POST /ai-tasks/{task_id}/retry; when it is false a retry cannot succeed — follow recommended_action instead.
4. Diagnostics to record
Record the HTTP status and body code (for a failed task, also data.status and data.error_code), the message, the request time, the endpoint path, and the session_id / task_id / report ID involved.
Redact logs
Never log a full x-api-key, Authorization header, private pet data, or sensitive user-provided content.