> ## 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-Hans/developers/v1/errors/unauthorized) | 401 | 否 |
| [`credential_inactive`](/zh-Hans/developers/v1/errors/credential_inactive) | 401 | 否 |
| [`credential_expired`](/zh-Hans/developers/v1/errors/credential_expired) | 401 | 否 |
| [`credential_revoked`](/zh-Hans/developers/v1/errors/credential_revoked) | 401 | 否 |
| [`not_entitled`](/zh-Hans/developers/v1/errors/not_entitled) | 403 | 否 |
| [`insufficient_permission`](/zh-Hans/developers/v1/errors/insufficient_permission) | 403 | 否 |
| [`permission_denied`](/zh-Hans/developers/v1/errors/permission_denied) | 403 | 否 |
| [`resource_not_found`](/zh-Hans/developers/v1/errors/resource_not_found) | 404 | 否 |
| [`invalid_request`](/zh-Hans/developers/v1/errors/invalid_request) | 400 或 409 | 否 |
| [`invalid_filter`](/zh-Hans/developers/v1/errors/invalid_filter) | 400 | 否 |
| [`unsupported_version`](/zh-Hans/developers/v1/errors/unsupported_version) | 400 | 否 |
| [`idempotency_key_reuse`](/zh-Hans/developers/v1/errors/idempotency_key_reuse) | 409 | 视冲突情况而定 |
| [`rate_limited`](/zh-Hans/developers/v1/errors/rate_limited) | 429 | 是 |
| [`service_unavailable`](/zh-Hans/developers/v1/errors/service_unavailable) | 503 | 是 |
| [`internal_error`](/zh-Hans/developers/v1/errors/internal_error) | 500 | 是 |

错误代码集是封闭的：新增代码属于公共契约变更，并将通过 API 变更日志发布公告。`retryable: true` 响应表示相关状况可能会自行恢复，但并不能证明写入操作没有产生任何影响。重试读取操作时，请设定有限的尝试次数和时间预算，并采用指数退避和抖动。如果存在 `Retry-After`，请予以遵循，包括在可重试的 `409` 或 `429` 响应中。

对于变更操作，请遵循该操作已记录的幂等性和恢复契约。在受支持的情况下，请保留原始密钥和原始请求。超时或出现 `5xx` 后，请勿另行生成新的密钥：这样做可能会导致已成功的写入被重复执行。对于不支持幂等性的操作，`Idempotency-Key` 标头不能提供任何保护。


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