> ## 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.

# Status das entidades e códigos de erro

> Status do ciclo de vida, status de documentos e provas derivados, formato de erro e catálogo de códigos de erro da API de Entidades.

Tabelas de referência para a API de Entidades: status do ciclo de vida, status derivados, formato de erro e catálogo de códigos de erro.

## Status da entidade

```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((Início)) --> PK[PENDING_KYC]
    PK --- L0(["Solicitar verificação"]):::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((Fim))
    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
```

| Status | Significado | Definido por |
| - | - | - |
| PENDING\_KYC | Criado e aguardando arquivos, ou devolvido para correção (motivo em statusReason). | Você (criação). Conformidade da Localpayment (correção). |
| IN\_REVIEW | Em análise pela Localpayment. Dados, documentos, arquivos e vínculos de UBO estão congelados. | Você, com Solicitar verificação |
| `ACTIVE` | Aprovado. | Conformidade da Localpayment |
| `REJECTED` | A revisão falhou. O motivo está no histórico de status. | Conformidade da Localpayment |
| `BLOCKED` | Bloqueado temporariamente. Motivo no histórico de status. | Conformidade da Localpayment |
| `CLOSED` | Excluído logicamente. Final. | Você (Fechar uma entidade) |

Você faz a criação, `IN_REVIEW` (com [Solicitar verificação](https://docs.localpayment.com/pt-br/reference/request-entity-verification.md)) e `CLOSED`; todas as outras transições são feitas pela Localpayment. Entidades `IN_REVIEW` rejeitam edições de dados, documentos, arquivos e vínculos de UBO com 409 `ENTITY_IN_REVIEW`. Entidades `REJECTED`, `BLOCKED` e `CLOSED` rejeitam edições, novos documentos e uploads com 409 `ENTITY_NOT_EDITABLE`.

## Status do documento (derivado)

| Status | Regra |
| - | - |
| `PENDING` | Ainda não há arquivo aprovado ou o arquivo está aguardando revisão. |
| `VERIFIED` | Pelo menos uma prova ativa, e todas elas APPROVED. |
| `REJECTED` | Pelo menos uma prova ativa REJECTED. |
| `EXPIRED` | expirationDate está no passado. Tem precedência sobre os outros status. |

## Status da revisão da prova (verificationStatus)

| Status | Significado |
| - | - |
| `PENDING` | Enviado, ainda não revisado. |
| IN\_REVIEW | Um analista da Localpayment abriu o documento. |
| `APPROVED` | Aceito. Versão final para esse arquivo. |
| `REJECTED` | Recusado. Consulte verificationReason. Substitua o arquivo enviando o mesmo proofType assim que a entidade não estiver IN\_REVIEW. |

## Ciclo de vida da prova (status)

| Status | Significado |
| - | - |
| `CURRENT` | O arquivo ativo do seu proofType no documento. |
| `SUPERSEDED` | Substituído por um upload mais recente do mesmo FRONT, BACK ou SELFIE. |
| `DELETED` | Removido com a opção "Excluir uma prova". Mantido para fins de auditoria. |

## Cobertura da documentação (documentationStatus)

| Valor | Significado |
| - | - |
| NO\_FILES | Nenhum documento possui um arquivo. |
| PARTIAL | Alguns documentos possuem arquivos. |
| COMPLETE | Cada documento possui pelo menos um arquivo. Isso não implica em aprovação. |

## Formato de erro

Os erros seguem a RFC 9457 (`application/problem+json`). `code` é uma string estável e legível por máquina, `details` indica o campo com problema quando aplicável, e `correlationId` identifica a requisição: informe-o ao entrar em contato com o suporte.

```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"
    }
  ]
}
```

Um conflito sem detalhes de campo:

```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": []
}
```

Use `code` para ramificar a lógica, não `title` nem `detail`: somente `code` tem garantia de permanecer estável.

## Códigos de erro

| HTTP | code | Causa |
| - | - | - |
| 400 | CUSTOM\_FIELDS\_INVALID | attributes não satisfaz o esquema de campos personalizados. details\[] lista o campo e o problema. |
| 400 | MISSING\_OR\_INVALID\_CLIENT\_CODE | Não foi possível identificar sua conta comercial a partir da solicitação. Verifique as credenciais que você está usando. |
| 400 | VALIDATION\_ERROR | Um campo, cabeçalho, parâmetro de caminho ou de consulta está ausente, é desconhecido ou inválido. details\[] lista o campo e o problema. |
| 401 | MISSING\_OR\_INVALID\_ACTOR | O token de acesso não identifica o usuário que realiza a ação. |
| 401 | `UNAUTHORIZED` | Token de acesso ausente ou inválido. |
| 403 | TENANT\_MISMATCH | A solicitação mistura identificadores de duas contas de comerciante. Verifique as credenciais que você está usando. |
| 404 | CLIENT\_NOT\_FOUND | A conta comercial em suas credenciais não existe no Localpayment. |
| 404 | CUSTOM\_FIELD\_SCHEMA\_NOT\_FOUND | Não há nenhum esquema de campos personalizados publicado para o seu comerciante. |
| 404 | DOCUMENT\_NOT\_FOUND | O documento não existe, foi apagado ou pertence a outro comerciante. |
| 404 | ENTITY\_NOT\_FOUND | A entidade não existe ou pertence a outro comerciante. |
| 404 | PROOF\_NOT\_FOUND | A prova não existe ou pertence a outro comerciante. |
| 404 | UBO\_NOT\_FOUND | O link UBO não existe, já expirou ou pertence a outro comerciante. |
| 409 | CONCURRENT\_MODIFICATION | Dois uploads do mesmo proofType no mesmo documento ocorreram ao mesmo tempo. Tente a solicitação novamente. |
| 409 | DUPLICATE\_ENTITY | externalId, ou o par type + id de um documento, já existe na sua conta de comerciante. |
| 409 | ENTITY\_IN\_REVIEW | A entidade está IN\_REVIEW: seus dados, documentos, arquivos e vínculos de UBO ficam congelados até que a Conformidade da Localpayment a resolva. |
| 409 | ENTITY\_NOT\_EDITABLE | A entidade está REJECTED, BLOCKED ou CLOSED, ou a operação removeria o documento principal ou o único documento. |
| 409 | INVALID\_STATUS\_TRANSITION | A entidade não está em um status que permita esta operação (por exemplo, uma entidade que já está CLOSED). |
| 409 | PROOF\_APPROVED | A prova está APPROVED: não pode ser substituída nem excluída. |
| 409 | PROOF\_SUPERSEDED | A prova foi substituída por um upload mais recente do mesmo proofType no mesmo documento. Somente a prova ativa é revisada. |
| 409 | UBO\_ALREADY\_LINKED | A pessoa já possui um vínculo UBO ativo com esta empresa. |
| 409 | UBO\_LIMIT\_EXCEEDED | A empresa já possui 50 links UBO ativos. |
| 412 | VERSION\_CONFLICT | A condição If-Match não corresponde à versão atual da entidade. Leia a entidade novamente e tente outra vez. |
| 413 | FILE\_TOO\_LARGE | O arquivo enviado excede 10 MB. |
| 413 | PAYLOAD\_TOO\_LARGE | attributes excede 64 KB. |
| 415 | UNSUPPORTED\_FILE\_TYPE | O arquivo enviado não é um JPG, PNG ou PDF. |
| 415 | UNSUPPORTED\_MEDIA\_TYPE | O Content-Type da requisição não é o esperado pelo endpoint (application/json ou multipart/form-data para uploads). |
| 422 | ENTITY\_NOT\_ACTIVE | A empresa (ou a pessoa) está CLOSED, BLOCKED ou REJECTED. |
| 422 | INCOMPLETE\_KYC\_DATA | Faltam os dados mínimos de KYC: name e lastname para INDIVIDUAL, name para COMPANY. |
| 422 | INVALID\_CONTROL\_ROLE | controlRole não é um dos códigos de função listados em Vincular um UBO. Os códigos diferenciam maiúsculas de minúsculas: director retorna este erro. |
| 422 | INVALID\_ENTITY\_TYPE | companyId deve ser uma COMPANY e personId uma INDIVIDUAL. |
| 422 | INVALID\_PERCENTAGE | ownershipPercentage está fora do intervalo de 0 a 100 ou tem mais de duas casas decimais. |
| 422 | INVALID\_VALIDITY\_RANGE | validTo é anterior a validFrom. |
| 422 | NO\_PROOFS\_UPLOADED | A entidade não tem arquivos enviados. Envie pelo menos um arquivo antes de solicitar a verificação. |
| 502 | STORAGE\_WRITE\_FAILED | Não foi possível salvar o arquivo. Tente novamente. |
| 503 | CLIENT\_DIRECTORY\_UNAVAILABLE | A Localpayment não conseguiu identificar sua conta de comerciante neste momento. Tente novamente mais tarde. |

Os erros sobre sua conta de comerciante (`MISSING_OR_INVALID_CLIENT_CODE`, `CLIENT_NOT_FOUND`, `TENANT_MISMATCH`, `MISSING_OR_INVALID_ACTOR`, `CLIENT_DIRECTORY_UNAVAILABLE`) vêm das credenciais no seu token de acesso, não do corpo da requisição. Verifique se você usa o token de acesso da conta de comerciante correta e entre em contato com o suporte com o `correlationId` se o erro persistir.


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