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

# 錯誤參考

> Living Security /v1 公用 API 可能傳回的所有錯誤，包括其穩定的機器碼、HTTP 狀態，以及解決方式。

每個 `/v1` 錯誤回應皆為 `application/problem+json`（[RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)），並包含一組固定欄位：

```json theme={null}
{
  "type": "https://docs.livingsecurity.com/developers/v1/errors/resource_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "No such organization.",
  "code": "resource_not_found",
  "request_id": "req_...",
  "doc_url": "https://docs.livingsecurity.com/developers/v1/errors/resource_not_found",
  "retryable": false
}
```

請依據 `code` 進行分支處理，切勿依據 `detail`——`code` 是穩定的機器契約；`detail` 為供人閱讀的文字，可能會變更。當錯誤可歸因於特定的請求參數時，會包含 `param`。聯絡支援團隊時，請附上 `request_id`。

## 錯誤碼

| 代碼 | HTTP 狀態 | 可重試 |
| - | - | - |
| [`unauthorized`](/zh-Hant/developers/v1/errors/unauthorized) | 401 | 否 |
| [`credential_inactive`](/zh-Hant/developers/v1/errors/credential_inactive) | 401 | 否 |
| [`credential_expired`](/zh-Hant/developers/v1/errors/credential_expired) | 401 | 否 |
| [`credential_revoked`](/zh-Hant/developers/v1/errors/credential_revoked) | 401 | 否 |
| [`not_entitled`](/zh-Hant/developers/v1/errors/not_entitled) | 403 | 否 |
| [`insufficient_permission`](/zh-Hant/developers/v1/errors/insufficient_permission) | 403 | 否 |
| [`permission_denied`](/zh-Hant/developers/v1/errors/permission_denied) | 403 | 否 |
| [`resource_not_found`](/zh-Hant/developers/v1/errors/resource_not_found) | 404 | 否 |
| [`invalid_request`](/zh-Hant/developers/v1/errors/invalid_request) | 400 或 409 | 否 |
| [`invalid_filter`](/zh-Hant/developers/v1/errors/invalid_filter) | 400 | 否 |
| [`unsupported_version`](/zh-Hant/developers/v1/errors/unsupported_version) | 400 | 否 |
| [`idempotency_key_reuse`](/zh-Hant/developers/v1/errors/idempotency_key_reuse) | 409 | 視衝突情況而定 |
| [`rate_limited`](/zh-Hant/developers/v1/errors/rate_limited) | 429 | 是 |
| [`service_unavailable`](/zh-Hant/developers/v1/errors/service_unavailable) | 503 | 是 |
| [`internal_error`](/zh-Hant/developers/v1/errors/internal_error) | 500 | 是 |

此代碼集為封閉集合：新增代碼屬於公用契約的變更，並會透過 API 變更記錄公告。`retryable: true` 回應表示該狀況可能會自行解除，但並不證明寫入作業未產生任何影響。重試讀取作業時，請設定有限的嘗試次數與時間預算，並採用指數退避與抖動（jitter）。若有 `Retry-After`，請予以遵循，包括在可重試的 `409` 或 `429` 回應中亦然。

對於變更作業，請遵循該作業所記載的等冪性與復原契約。在支援的情況下，請保留原始金鑰與請求。發生逾時或 `5xx` 後，請勿自行產生新的金鑰：這樣做可能會重複執行已成功的寫入作業。對於不支援 `Idempotency-Key` 標頭的作業，該標頭無法提供任何保護。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.