稀疏空间地图 APIs 錯誤碼說明
響應格式
所有 API 響應均採用統一的 JSON 格式，以下是一個範例 :
{
"statusCode": 119,
"msg": "Parameter has errors",
"date": "2022-06-15T09:56:30.000Z",
"result": //statusCode 為 0 的情況才有 result，如果發生錯誤，結果欄位為空
}
| 欄位 | 類型 | 說明 |
|---|---|---|
| statusCode | integer | 業務狀態碼，0 表示成功，非 0 表示錯誤 |
| msg | string | 訊息 |
| result | object | 返回內容，狀態碼是 0 時響應目標圖物件結構，否則為空 |
| date | string | 伺服器時間 |
重要事項
statusCode == 0 的條件下，result 才包括響應內容，其它狀態下 result 為空
statusCode != 0 的條件下，請關注錯誤訊息 msg
錯誤碼分類
HTTP 狀態碼說明
| HTTP 狀態碼 | 說明 |
|---|---|
| 200 | 請求成功（可能包含業務錯誤） |
| 400 | 請求參數錯誤 |
| 401 | APIKey 認證失敗 |
| 403 | 權限不足或資源禁止存取 |
| 404 | 請求 URL 介面 Path 不存在 |
| 500 | 伺服器內部錯誤 |
| 502 | 應用異常捕獲，可能資料錯誤 |
注意：業務錯誤通常透過 HTTP 200 響應返回，在 statusCode 欄位中標識具體錯誤類型。
業務狀態碼一覽表
| Status Code | Message |
|---|---|
| 0 | Success |
| 101 | Uploaded file is empty |
| 102 | File size is too large |
| 106 | Missing parameter or parameter is empty |
| 110 | Call server API errors |
| 111 | Resource not found |
| 401 | Authentication token expired |
| 401 | Authentication parameter is missing |
| 401 | Unknown appId or appKey |
| 401 | Account is locked |
| 401 | Authentication failed, invalid signature or token |
常見錯誤場景
超時無響應
- Request Timeout：網路比較慢，建議檢查客戶端的網路環境
認證相關錯誤
- Http 401 Unauthorized：APIKey 認證失敗，檢查 appId/appKey 是否正確
- 狀態碼 401：應用金鑰無效或應用不存在，檢查應用配置
參數錯誤
- 400 Bad Request：請求參數格式錯誤
資源操作錯誤
- 狀態碼 10x：查詢的目標資源不存在，或者參數錯誤
系統錯誤
- Http 50x Internal Server Error：伺服器內部異常或者應用異常捕獲，建議在網站上測試或者 sample 測試
最佳實踐建議
- 客戶端處理：建議根據
statusCode欄位判斷業務是否成功，而非僅依賴 HTTP 狀態碼 - 錯誤重試：對於 5xx 錯誤可適當重試，對於 4xx 錯誤需檢查請求參數
- 日誌記錄：建議記錄完整的錯誤響應，便於問題排查
- 超時處理：設定合理的請求超時時間，避免長時間等待