Skip to content

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) ​

json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
  • code: Always 200 on 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:

json
{
  "code": 10002,
  "error_code": "INVALID_API_KEY",
  "message": "The API key is invalid or has expired",
  "data": null,
  "call_id": "call_94b5952f4dc248dbb4f6236bb5ff64cf"
}

Field definitions:

FieldTypeDescription
codeintegerUnified numeric status code. Always 200 on success; 5-digit business error code on failure (e.g. 10002)
error_codestringMachine-readable uppercase string constant (e.g. INVALID_API_KEY) for programmatic branch logic
messagestringUser-friendly error message description
datanullAlways null on failure
call_idstringUnique 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:

RangeDomainHTTP MappingPrimary Scenarios
200Success200Request completed normally
10000 ~ 19999Auth & Permissions401 / 403Missing credentials, invalid API key, expired token, forbidden capability
20000 ~ 29999Request & Params400 / 415 / 422Malformed JSON, validation failure, unsupported media type, not found
30000 ~ 39999Billing & Quotas402 / 429Quota exhausted, insufficient balance, rate limit exceeded
50000 ~ 59999Service & Maintenance500 / 502 / 503 / 504Service busy, please retry later

Common Error Codes Reference ​

codeerror_codeHTTP StatusDescription & Recommended Action
10001UNAUTHORIZED401Missing authentication credentials (Authorization or x-api-key)
10002INVALID_API_KEY401 / 403API key is invalid or deactivated
10003TOKEN_EXPIRED401Access token expired; exchange for a new token
10004TOKEN_REVOKED401Token was explicitly revoked
10005INSUFFICIENT_SCOPE403API key lacks permission to call this capability
10006CAPABILITY_FORBIDDEN403Capability not enabled for current project
10007USER_DISABLED403User account has been deactivated
10008PROJECT_DISABLED403Project is deactivated
10009CLIENT_TOKEN_REQUIRED401Client-side call requires a valid client token
20001INVALID_REQUEST400Request body or parameters are invalid
20002VALIDATION_ERROR422Request validation failed (missing required field, value out of range)
20003UNSUPPORTED_MEDIA_TYPE415Unsupported media type (e.g. file upload not using multipart/form-data)
20004REQUEST_BODY_TOO_LARGE413Request body exceeds maximum allowed size
20005RESOURCE_NOT_FOUND404Route, task, file, or resource entity not found
20006IDEMPOTENCY_CONFLICT409Conflicting request with the same idempotency key
30001QUOTA_EXHAUSTED402 / 403Free quota has been exhausted
30002INSUFFICIENT_BALANCE402Account wallet balance insufficient for invocation
30003RATE_LIMIT_EXCEEDED429Rate limit or concurrency limit exceeded; retry with exponential backoff
50001SERVICE_BUSY500 / 502 / 503 / 504Service 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:

text
data: {"type":"error","code":"AI_DOC_CONTINUE_STREAM_FAILED","error_code":5401,"message":"流式判断是否继续追问失败","retryable":true,"recommended_action":"retry_later"}
Event typeDescriptionData format
errorTerminal 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:

json
{
  "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 or code.
  • data.error_code: the public numeric code when the task failed; null otherwise.
  • The envelope has only code, message and data — there is no top-level error_code; you must parse data to 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_codeMeaningretryablerecommended_action
4001Invalid request parameters or business inputfalsecorrect_request
4002Missing or invalid credentialsfalsesign_in
4003Not permitted to perform this operationfalsego_back
4004Requested resource does not existfalsego_back
4005Submitted content exceeds the size limitfalsereduce_file_size
4101The image is not suitable for this recognitionfalsereplace_image
4102Select an image before recognitionfalsereplace_image
4103Image is too largefalsereduce_file_size
4104Unsupported image formatfalsereplace_image
4105Empty or invalid image filefalsereupload_media
4106Invalid image addressfalsereupload_media
4107Unsupported image sourcefalsereupload_media
4108Image temporarily unreachabletrueretry_later
4501Unsupported media format or typefalsereupload_media
4502This media cannot be used for the current businessfalsereupload_media
4503Media integrity check failedfalsereupload_media
4504Media file exceeds the size limitfalsereduce_file_size
4505Media file is empty or unreadablefalsereupload_media
5001Service temporarily unavailabletrueretry_later
5002Service busytrueretry_later
5003Task submission failedtrueretry_later
5004Dependent service temporarily unavailabletrueretry_later
5101Image-recognition service timed outtrueretry_later
5102Image-recognition service temporarily unavailabletrueretry_later
5103Image-recognition configuration unavailabletrueretry_later
5104Image-recognition result generation failedtrueretry_later
5105Image report generation incompletetrueretry_later
5106Image-recognition connection interruptedtrueretry_later
5401Smart Consultation connection interruptedtrueretry_later
5501Media storage temporarily unavailabletrueretry_later
5502Media processing temporarily unavailabletrueretry_later
5503Invalid media processing resulttrueretry_later
6001Request conflicts with an existing taskfalseuse_existing_task
6002Current task state does not allow this operationfalserefresh_state
6003Task canceledfalserefresh_state
6004Task expiredfalserefresh_state
6101Image is being analysedtruewait_and_poll
6102Image report task already submittedfalseuse_existing_task
6103Image-recognition type does not match this sessionfalserestart_session
6106Session language does not matchfalserestart_session
6501Media file not ready yettruewait_and_poll
6502Media file does not match the current taskfalsereupload_media
6503Media processing stage not eligibletruewait_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.

最近更新

Qijie Open Platform · API Documentation