Cloud recognition APIs error code description
Response format
All API responses adopt a unified JSON format. Below 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, 0 indicates success, non-0 indicates error |
| result | string | Return content. When status code is 0, it returns the target image object structure; otherwise returns an error message |
| timestamp | long | Server Unix format timestamp (millisecond level) |
Important
Only when statusCode == 0, result includes response content. In other states, 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 | Requested 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 typically returned through 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
Timeout no response
- Request Timeout: Network is slow. Recommended to check client network environment
Authentication-related errors
- Http 401 Unauthorized: APIKey authentication failed. Verify appId/appKey correctness
- Status code 401: Invalid application key or application does not exist. Check application configuration
Parameter errors
- 400 Bad Request: Request parameter format error
- Status code 414: Required parameter missing or parameter value doesn't meet requirements
Resource operation errors
- Status code 404: Queried target resource does not exist
- Status code 403: Target already exists, cannot create duplicate
- Status code 417/420/424: Create/delete/modify operation failed
File-related errors
- Status code 422: Uploaded file size exceeds limit
- Status code 427: Image format not supported or file corrupted
System errors
- Http 500 Internal Server Error: Internal server exception. Recommended to test on website or using sample
- Http 501 Exception: Application exception caught, possible data error. Recommended to test on website or using sample
- Http 502 Server: Service response error. Likely server issue. Recommended to contact us
Best practice recommendations
- Client handling: Recommend judging business success based on
statusCodefield, not solely relying on HTTP status code - Error retry: May retry for 5xx errors appropriately. For 4xx errors, need to check request parameters
- Logging: Recommend recording complete error responses for troubleshooting
- Timeout handling: Set reasonable request timeout duration to avoid prolonged waiting