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

# 錯誤

> 解析一致的 REST API 錯誤回應格式與請求識別碼。

每個非 2xx 回應都使用一致的 JSON 格式。請依穩定的 `error.code` 分類錯誤，不要依賴供人閱讀的 `message`。

## 錯誤回應格式

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request could not be validated.",
    "request_id": "req_demo_001",
    "details": {
      "fields": [
        { "path": "recipient.phone_number", "code": "invalid_e164" }
      ]
    }
  }
}
```

`details` 為非必填且可供機器讀取的內容。客戶端應忽略 `details` 中的未知欄位。

## 請求關聯

每個回應都包含 `X-Request-Id` 標頭，錯誤內容也會在 `error.request_id` 重複同一值。請將該識別碼與失敗操作一起記錄，並在聯絡 Brightalk 支援時提供。不要記錄 API 金鑰或完整聯絡人資料。

您可以傳送 `X-Request-Id`，使用 1–64 個 `A-Z`、`a-z`、`0-9`、`.`、`_`、`:` 或 `-` 字元。若省略或傳送不合格式的值，Brightalk 會改用產生的識別碼。

## 身分驗證錯誤的差異

| 情況                                  | HTTP 狀態與錯誤碼                   |
| ----------------------------------- | ----------------------------- |
| 缺少 `Authorization`，或不符合精確 bearer 語法 | `401 authentication_required` |
| Bearer 語法正確，但金鑰不存在或已撤銷              | `401 invalid_api_key`         |
| 金鑰已過期                               | `401 api_key_expired`         |

這些回應只描述憑證是否可用，不會洩漏其他組織的資源。

## 狀態與錯誤目錄

| HTTP 狀態 | 穩定錯誤碼                                                                                                                         |
| ------: | ----------------------------------------------------------------------------------------------------------------------------- |
|   `400` | `unsupported_version`、`validation_error`、`invalid_json`、`unsupported_destination`、`idempotency_key_required`                  |
|   `401` | `authentication_required`、`invalid_api_key`、`api_key_expired`                                                                 |
|   `403` | `organization_not_enabled`、`insufficient_scope`                                                                               |
|   `404` | `resource_not_found`                                                                                                          |
|   `405` | `method_not_allowed`                                                                                                          |
|   `409` | `resource_state_conflict`、`contact_identity_conflict`、`idempotency_conflict`、`idempotency_in_progress`、`duplicate_active_run` |
|   `413` | `request_too_large`                                                                                                           |
|   `429` | `rate_limit_exceeded`                                                                                                         |
|   `500` | `internal_error`                                                                                                              |

對已知路徑使用不支援的方法時，回應也包含 `Allow`。適合等待後重試的情況會包含 `Retry-After`。錯誤回應絕不揭露實作名稱、內部資料內容、查詢細節或堆疊追蹤。