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

# 实体状态和错误代码

> 实体 API 的生命周期状态、派生文档和证明状态、错误格式和错误代码目录。

实体 API 的参考表：生命周期状态、派生状态、错误格式和错误代码目录。

## 实体状态

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    S((开始)) --> PK[PENDING_KYC]
    PK --- L0(["请求验证"]):::lbl --> IR[IN_REVIEW]
    IR --> PK
    IR --> AC[ACTIVE]
    IR --> RJ[REJECTED]
    AC --> BL[BLOCKED]
    BL --> AC
    PK --> CL[CLOSED]
    IR --> CL
    AC --> CL
    BL --> CL
    RJ --> CL
    CL --> E((结束))
    class S,E terminal
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px
```

| 状态 | 意义 | 设置方 |
| - | - | - |
| PENDING\_KYC | 已创建并等待文件，或已退回进行更正（原因在 statusReason 中）。 | 您（创建）。Localpayment 合规团队（更正）。 |
| IN\_REVIEW | Localpayment 正在审核。数据、文档、文件和 UBO 关联已冻结。 | 您，通过请求验证 |
| `ACTIVE` | 已批准。 | Localpayment 合规团队 |
| `REJECTED` | 审核失败。原因请查看状态历史记录。 | Localpayment 合规团队 |
| `BLOCKED` | 暂时封禁。原因请查看状态历史记录。 | Localpayment 合规团队 |
| `CLOSED` | 逻辑删除。最终版本。 | 您（关闭实体） |

创建、`IN_REVIEW`（通过[请求验证](https://docs.localpayment.com/zh/reference/request-entity-verification.md)）和 `CLOSED` 由您操作；其他所有状态转换均由 Localpayment 完成。处于 `IN_REVIEW` 状态的实体会拒绝对数据、文档、文件和 UBO 关联的编辑，并返回 409 `ENTITY_IN_REVIEW`。处于 `REJECTED`、`BLOCKED` 和 `CLOSED` 状态的实体会拒绝编辑、新增文档和上传，并返回 409 `ENTITY_NOT_EDITABLE`。

## 文件状态（衍生）

| 状态 | 规则 |
| - | - |
| `PENDING` | 目前还没有获批的文件，或者文件正在等待审核。 |
| `VERIFIED` | 至少有一份有效证明，且全部已获批准。 |
| `REJECTED` | 至少有一项有效证明被驳回。 |
| `EXPIRED` | expirationDate 已过，优先级高于其他状态。 |

## 证明审核状态（verificationStatus）

| 状态 | 意义 |
| - | - |
| `PENDING` | 已上传，尚未审核。 |
| IN\_REVIEW | 一位 Localpayment 审核员已打开该文件。 |
| `APPROVED` | 已接受。该文件已最终定稿。 |
| `REJECTED` | 已拒绝。请查看 verificationReason。待实体状态不再为 IN\_REVIEW 后，请上传相同 proofType 的文件以替换该文件。 |

## 证明生命周期（status）

| 状态 | 意义 |
| - | - |
| `CURRENT` | 该文档上对应 proofType 的有效文件。 |
| `SUPERSEDED` | 已被同一 FRONT、BACK 或 SELFIE 的较新上传文件取代。 |
| `DELETED` | 已使用“删除证据”功能移除。保留以供审核。 |

## 文档覆盖率（documentationStatus）

| 值 | 意义 |
| - | - |
| NO\_FILES | 没有任何文档包含文件。 |
| PARTIAL | 部分文档包含文件。 |
| COMPLETE | 每份文件至少包含一个附件。这并不代表已获批准。 |

## 错误格式

错误遵循 RFC 9457（`application/problem+json`）。`code` 是稳定的机器可读字符串，`details` 在适用时指明出错的字段，`correlationId` 用于标识请求：联系支持团队时请提供该值。

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation error",
  "instance": "/api/entity/v1/entities",
  "code": "CUSTOM_FIELDS_INVALID",
  "correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
  "details": [
    {
      "field": "numberOfEmployees",
      "issue": "NOT_IN_OPTIONS"
    },
    {
      "field": "legacyNote",
      "issue": "UNKNOWN_FIELD"
    }
  ]
}
```

不含字段详情的冲突：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Conflict",
  "instance": "/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos",
  "code": "UBO_ALREADY_LINKED",
  "correlationId": "acdfa68b-e1da-4764-84df-0a1e949d0939",
  "details": []
}
```

请基于 `code` 做分支判断，而不要依据 `title` 或 `detail`：只有 `code` 能保证保持稳定。

## 错误代码

| HTTP | code | 原因 |
| - | - | - |
| 400 | CUSTOM\_FIELDS\_INVALID | attributes 不符合您的自定义字段架构。details\[] 列出了字段和问题。 |
| 400 | MISSING\_OR\_INVALID\_CLIENT\_CODE | 请求中无法识别您的商户账户。请检查您使用的凭证。 |
| 400 | VALIDATION\_ERROR | 字段、标头、路径或查询参数缺失、未知或无效。details\[] 列出了字段和问题。 |
| 401 | MISSING\_OR\_INVALID\_ACTOR | 访问令牌无法识别执行操作的用户。 |
| 401 | `UNAUTHORIZED` | 缺少或无效的访问令牌。 |
| 403 | TENANT\_MISMATCH | 该请求混合使用了两个商户账户的标识符。请检查您使用的凭证。 |
| 404 | CLIENT\_NOT\_FOUND | 您提供的凭证中的商户账户在 Localpayment 中不存在。 |
| 404 | CUSTOM\_FIELD\_SCHEMA\_NOT\_FOUND | 您的商户未发布任何自定义字段架构。 |
| 404 | DOCUMENT\_NOT\_FOUND | 该文件不存在、已被删除或属于其他商家。 |
| 404 | ENTITY\_NOT\_FOUND | 该实体不存在或属于其他商家。 |
| 404 | PROOF\_NOT\_FOUND | 该证明不存在，或者属于其他商家。 |
| 404 | UBO\_NOT\_FOUND | UBO 链接不存在、已失效或属于其他商家。 |
| 409 | CONCURRENT\_MODIFICATION | 同一文档上相同 proofType 的两次上传同时发生。请重试请求。 |
| 409 | DUPLICATE\_ENTITY | externalId，或者文档的类型 + id 对，已存在于您的商户中。 |
| 409 | ENTITY\_IN\_REVIEW | 该实体处于 IN\_REVIEW 状态：在 Localpayment 合规团队处理完毕之前，其数据、文档、文件和 UBO 关联均被冻结。 |
| 409 | ENTITY\_NOT\_EDITABLE | 该实体处于 REJECTED、BLOCKED 或 CLOSED 状态，或该操作会删除主文档或唯一文档。 |
| 409 | INVALID\_STATUS\_TRANSITION | 该实体当前状态不允许此操作（例如，已处于 CLOSED 状态的实体）。 |
| 409 | PROOF\_APPROVED | 该证明为 APPROVED 状态：不可替换或删除。 |
| 409 | PROOF\_SUPERSEDED | 该证明已被同一文档上相同 proofType 的较新上传文件取代。仅审核当前有效的证明。 |
| 409 | UBO\_ALREADY\_LINKED | 此人已与该公司存在有效的最终受益所有人 (UBO) 关系。 |
| 409 | UBO\_LIMIT\_EXCEEDED | 该公司已有 50 个活跃的 UBO 链接。 |
| 412 | VERSION\_CONFLICT | If-Match 与当前实体版本不匹配。请重新读取实体并重试。 |
| 413 | FILE\_TOO\_LARGE | 上传的文件超过 10 MB。 |
| 413 | PAYLOAD\_TOO\_LARGE | attributes 超过 64 KB。 |
| 415 | UNSUPPORTED\_FILE\_TYPE | 上传的文件不是 JPG、PNG 或 PDF 格式。 |
| 415 | UNSUPPORTED\_MEDIA\_TYPE | 请求的 Content-Type 不是 endpoint 期望的类型（application/json，或用于上传的 multipart/form-data）。 |
| 422 | ENTITY\_NOT\_ACTIVE | 公司（或个人）处于 CLOSED、BLOCKED 或 REJECTED 状态。 |
| 422 | INCOMPLETE\_KYC\_DATA | 缺少最低限度的 KYC 数据：INDIVIDUAL 需要 name 和 lastname，COMPANY 需要 name。 |
| 422 | INVALID\_CONTROL\_ROLE | controlRole 不是“链接 UBO”中列出的角色代码之一。代码区分大小写：director 会返回此错误。 |
| 422 | INVALID\_ENTITY\_TYPE | companyId 必须是 COMPANY，personId 必须是 INDIVIDUAL。 |
| 422 | INVALID\_PERCENTAGE | ownershipPercentage 不在 0 到 100 的范围内，或小数位超过两位。 |
| 422 | INVALID\_VALIDITY\_RANGE | validTo 早于 validFrom。 |
| 422 | NO\_PROOFS\_UPLOADED | 该实体没有已上传的文件。请求验证之前，请至少上传一个文件。 |
| 502 | STORAGE\_WRITE\_FAILED | 文件无法保存，请重试上传。 |
| 503 | CLIENT\_DIRECTORY\_UNAVAILABLE | 目前 Localpayment 无法解析您的商户账户。请稍后重试。 |

涉及您商户账户的错误（`MISSING_OR_INVALID_CLIENT_CODE`、`CLIENT_NOT_FOUND`、`TENANT_MISMATCH`、`MISSING_OR_INVALID_ACTOR`、`CLIENT_DIRECTORY_UNAVAILABLE`）来自您访问令牌中的凭证，而不是请求体。请确认您使用的是正确商户账户的访问令牌；如果错误持续出现，请携带 `correlationId` 联系支持团队。


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