Cloud recognition APIs error code description
Response format
All API responses follow a unified JSON format. Here is an example:
{
"statusCode": 422,
"reuslt": "The image or meta exceeds its maximum permitted size",
"timestamp": 1514736000000,
"appKey": "test_app_key"
}
| Field | Type | Description |
|---|---|---|
| statusCode | integer | Business status code, where 0 indicates success and non-0 indicates an error |
| result | string | Return content. When the status code is 0, the response includes the target image object structure; otherwise, it returns an error message |
| timestamp | long | Server Unix-format timestamp (in milliseconds) |
Important
Only when statusCode == 0 will the result include the response content. In other cases, the result returns an error message.
Error code classification
HTTP status code description
| HTTP Status Code | Description |
|---|---|
| 200 | Request successful (may contain business errors) |
| 400 | Request parameter error |
| 401 | APIKey authentication failed |
| 403 | Insufficient permissions or resource access forbidden |
| 404 | Request URL interface path does not exist |
| 500 | Internal server error |
| 501 | Application exception caught, possible data error |
| 502 | Server unavailable, contact customer service |
Note
Business errors are usually returned via HTTP 200 responses, with specific error types identified in the statusCode field.
Business status code list
| Status Code | Message |
|---|---|
| 0 | ok |
| 1 | invalid appId (appKey) |
| 2 | invalid signature |
| 3 | invalid date |
| 4 | appId (appKey) not exist |
| 6 | invalid token |
| 6 | invalid appkey token |
| 7 | non-sdk client for dau databases |
| 8 | Dau databases are not compatible with sense-4.6+ any more. |
| 404 | Target not found |
| 414 | Parameter required not exists or not correct |
| 422 | The image or meta exceeds its maximum permitted size |
| 417 | fail to add image |
| 419 | Cannot update target in database because similar target exists. |
| 420 | Target delete failed |
| 424 | Target enable error |
| 403 | Target already exists |
| 426 | Judge exceeds maxium candidates |
| 427 | Image not correct |
Common error scenarios
Request timeout
- Request Timeout: The network is relatively slow. It is recommended to check the client's network environment.
Authentication-related errors
- Http 401 Unauthorized: APIKey authentication failed, check if appId/appKey is correct
- Status code 401: Invalid application key or application does not exist, check application configuration
Parameter error
- 400 Bad Request: request parameter format error
- Status code 414: required parameter missing or parameter value does not meet requirements
Resource operation error
- Status code 404: The target resource being queried does not exist
- Status code 403: The target already exists and cannot be created repeatedly
- Status code 417/420/424: Add, delete, or modify operation failed
File-related errors
- Status code 422: Uploaded file size exceeds the limit
- Status code 427: Image format not supported or file corrupted
System error
- Http 500 Internal Server Error: Internal server exception, recommended to test on the website or sample test
- Http 501 Exception: Application exception caught, possible data error, recommended to test on the website or sample test
- Http 502 Server: Service response error, possible server error, recommended to contact us
Best practice recommendations
- Client-side handling: It is recommended to determine business success based on the
statusCodefield rather than relying solely on HTTP status codes - Error retry: For 5xx errors, appropriate retries can be made, while for 4xx errors, request parameters need to be checked
- Logging: It is recommended to log complete error responses for troubleshooting
- Timeout handling: Set reasonable request timeout periods to avoid prolonged waiting