雲識別 APIs 錯誤碼說明
響應格式
所有 API 響應均採用統一的 JSON 格式，以下是一個範例 :
{
"statusCode": 422,
"reuslt": "The image or meta exceeds its maximum permitted size",
"timestamp": 1514736000000,
"appKey": "test_app_key"
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| statusCode | integer | 業務狀態碼，0 表示成功，非 0 表示錯誤 |
| result | string | 返回內容，狀態碼是 0 時響應目標圖物件結構，否則就返回錯誤訊息 |
| timestamp | long | 伺服器 Unix 格式時間戳（毫秒級） |
重要事項
statusCode == 0 的條件下，result 才包括響應內容，其它狀態下 result 返回錯誤訊息。
錯誤碼分類
HTTP 狀態碼說明
| HTTP 狀態碼 | 說明 |
|---|---|
| 200 | 請求成功（可能包含業務錯誤） |
| 400 | 請求參數錯誤 |
| 401 | APIKey 認證失敗 |
| 403 | 權限不足或資源禁止存取 |
| 404 | 請求 URL 接口 Path 不存在 |
| 500 | 伺服器內部錯誤 |
| 501 | 應用異常捕獲，可能資料錯誤 |
| 502 | 伺服器不可用，聯繫客服 |
附註
業務錯誤通常通過 HTTP 200 響應返回，在 statusCode 欄位中標識具體錯誤類型。
業務狀態碼一覽表
| 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 |
常見錯誤場景
超時無響應
- Request Timeout：網路比較慢，建議檢查客戶端的網路環境
認證相關錯誤
- Http 401 Unauthorized：APIKey 認證失敗，檢查 appId/appKey 是否正確
- 狀態碼 401：應用密鑰無效或應用不存在，檢查應用配置
參數錯誤
- 400 Bad Request：請求參數格式錯誤
- 狀態碼 414：必填參數缺失或參數值不符合要求
資源操作錯誤
- 狀態碼 404：查詢的目標資源不存在
- 狀態碼 403：目標已存在，無法重複建立
- 狀態碼 417/420/424：增刪改操作失敗
檔案相關錯誤
- 狀態碼 422：上傳的檔案大小超過限制
- 狀態碼 427：圖片格式不支援或檔案損壞
系統錯誤
- Http 500 Internal Server Error：伺服器內部異常，建議在網站上測試或者 sample 測試
- Http 501 Exception：應用異常捕獲，可能資料錯誤，建議在網站上測試或者 sample 測試
- Http 502 Server：服務響應錯誤，建議可能伺服器錯誤，建議聯繫我們
最佳實踐建議
- 客戶端處理：建議根據
statusCode欄位判斷業務是否成功，而非僅依賴 HTTP 狀態碼 - 錯誤重試：對於 5xx 錯誤可適當重試，對於 4xx 錯誤需檢查請求參數
- 日誌記錄：建議記錄完整的錯誤響應，便於問題排查
- 超時處理：設定合理的請求超時時間，避免長時間等待