> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexrex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 錯誤

> 一致的錯誤信封格式與所有機器可讀的錯誤代碼。

所有錯誤共用同一個信封格式。請依據 `code` 欄位進行分支，而非依賴人類可讀的 `error` 訊息
（後者可能變動），並記錄 `request_id` 以便支援使用。

```json theme={null}
{
  "success": false,
  "error": "API key lacks required scope: activities:read",
  "code": "missing_scope",
  "request_id": "req_9f2c…"
}
```

## 代碼

| 代碼                    | HTTP | 說明                                                  |
| --------------------- | ---- | --------------------------------------------------- |
| `invalid_key`         | 401  | 金鑰不存在或無法解析                                          |
| `key_expired`         | 401  | 金鑰已超過到期日                                            |
| `key_revoked`         | 401  | 金鑰已被機構撤銷                                            |
| `feature_not_enabled` | 403  | 此機構的方案未啟用 Developer API                             |
| `missing_scope`       | 403  | 金鑰缺少此端點所需的[存取範圍](/zh-Hant/api-reference/scopes)     |
| `not_found`           | 404  | 資源不存在**或**此金鑰無法看見該資源                                |
| `rate_limited`        | 429  | 超過每個金鑰的[請求頻率限制](/zh-Hant/api-reference/rate-limits) |
| `validation_error`    | 400  | 請求參數或請求本體欄位驗證失敗                                     |

## 特定代碼說明

* **`not_found` 會隱藏資源是否存在。** 當金鑰請求屬於其他機構的運動員、活動或匯出任務，
  或由其他金鑰建立的匯出任務時，API 回傳 `404` 而非 `403`。這是刻意設計的：
  金鑰永遠無法得知它無法存取的資源是否存在。
* **`key_expired` vs `key_revoked` vs `invalid_key`。** 三者有所區分，
  讓你的整合能正確應對——到期時提示取得新金鑰、撤銷時通知管理員，
  並將 `invalid_key` 視為設定錯誤。
* **`feature_not_enabled`** 表示該機構的方案未包含 Developer API 存取權。
  請聯繫機構管理員以升級至 Club 方案。