開放平台 API 狀態碼說明文件
文件說明
本文件定義開放平台 API 介面回傳的狀態碼規範，用於釐清介面呼叫結果、錯誤類型與原因，協助開發者快速定位與排除問題。所有 API 介面均依此狀態碼規則回傳結果。
狀態碼分類規則
| 狀態碼段 | 分類說明 |
|---|---|
| 200 | 成功（介面呼叫正常完成） |
| 1xxxx | 通用錯誤（非分類性異常） |
| 2xxxx | 認證授權相關錯誤 |
| 4xxxx | 請求／參數校驗相關錯誤 |
| 5xxxx | 介面相關錯誤 |
| 6xxxx | 限流相關錯誤 |
| 7xxxx | 業務邏輯相關錯誤 |
狀態碼詳情
1. 成功狀態碼
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 200 | SUCCESS | 介面呼叫成功 |
2. 通用錯誤（1xxxx）
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 10000 | UNKNOWN_ERROR | 未知錯誤，請聯絡技術支援 |
3. 認證授權相關錯誤（2xxxx）
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 20001 | API_KEY_MISSING | API 金鑰缺失（請求中未攜帶 API Key 參數） |
| 20002 | API_KEY_INVALID | 無效的 API 金鑰（已停用、過期或未審核通過） |
| 20010 | TIMESTAMP_MISSING | 時間戳參數缺失（請求中未攜帶 timestamp 參數） |
| 20011 | TIMESTAMP_FORMAT_ERROR | 時間戳格式錯誤（必須為 10 位或 13 位數字） |
| 20012 | TIMESTAMP_EXPIRED | 時間戳已過期（請求逾時，需重新產生時間戳後再呼叫） |
| 20020 | SIGNATURE_MISSING | 簽名參數缺失（請求中未攜帶 signature 參數） |
| 20021 | SIGNATURE_VERIFY_FAILED | 簽名驗證失敗（簽名產生規則錯誤或參數遭竄改） |
4. 請求／參數校驗相關錯誤（4xxxx）
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 400 | INVALID_REQUEST | 請求主體無法解析（請檢查請求參數傳遞方式是否符合文件要求） |
| 404 | NOT_FOUND | 介面路徑不存在（請檢查請求路徑是否正確） |
| 405 | REQUEST_METHOD_NOT_ALLOWED | 請求方法不允許（請檢查請求方法是否符合文件要求） |
| 40001 | REQUIRED_PARAMS_EMPTY | 必填參數缺失（介面要求的必傳參數未提交） |
| 40002 | REQUIRED_PARAMS_ILLEGAL | 請求參數不合法（參數格式／取值範圍不符合要求） |
5. 介面相關錯誤（5xxxx）
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 50001 | INTERFACE_NOT_FOUND | API 介面不存在（請求路徑錯誤） |
6. 限流相關錯誤（6xxxx）
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 60001 | INTERFACE_RATE_LIMIT | 介面呼叫頻率超限，請稍後重試 |
7. 業務邏輯相關錯誤（7xxxx）
| 狀態碼 | 列舉識別 | 說明 |
|---|---|---|
| 70001 | NOT_ENOUGH_CREDIT | 帳戶餘額不足，請儲值 |