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

# Estados de las entidades y códigos de error

> Estados del ciclo de vida, estados de documentos derivados y pruebas, formato de error y catálogo de códigos de error de la API de entidades.

Tablas de referencia para la API de entidades: estados del ciclo de vida, estados derivados, formato de error y catálogo de códigos de error.

## Estado de la entidad

```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((Inicio)) --> PK[PENDING_KYC]
    PK --- L0(["Solicitar verificación"]):::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((Fin))
    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 | Establecido por |
| - | - | - |
| PENDING\_KYC | Creada y a la espera de archivos, o devuelta para corrección (motivo en statusReason). | Tú (creación). Cumplimiento de Localpayment (corrección). |
| IN\_REVIEW | En revisión por Localpayment. Los datos, documentos, archivos y vínculos UBO están congelados. | Tú, con la verificación de la solicitud |
| `ACTIVE` | Aprobado. | Localpayment Compliance |
| `REJECTED` | La revisión ha fallado. El motivo se encuentra en el historial de estado. | Localpayment Compliance |
| `BLOCKED` | Bloqueado temporalmente. El motivo se encuentra en el historial de estado. | Localpayment Compliance |
| `CLOSED` | Eliminado lógicamente. Final. | Tú (Cerrar una entidad) |

Tú realizas la creación, `IN_REVIEW` (con [Solicitar verificación](https://docs.localpayment.com/es/reference/request-entity-verification.md)) y `CLOSED`; todas las demás transiciones las realiza Localpayment. Las entidades en `IN_REVIEW` rechazan las ediciones de datos, documentos, archivos y vínculos UBO con el error 409 `ENTITY_IN_REVIEW`. Las entidades `REJECTED`, `BLOCKED` y `CLOSED` rechazan las ediciones, los nuevos documentos y las cargas con el error 409 `ENTITY_NOT_EDITABLE`.

## Estado del documento (derivado)

| Status | Regla |
| - | - |
| `PENDING` | Aún no hay ningún archivo aprobado, o el archivo está pendiente de revisión. |
| `VERIFIED` | Al menos una prueba activa, y todas ellas APPROVED. |
| `REJECTED` | Al menos una prueba activa REJECTED. |
| `EXPIRED` | expirationDate está en el pasado. Tiene prioridad sobre los demás estados. |

## Estado de revisión de pruebas (verificationStatus)

| Status | Meaning |
| - | - |
| `PENDING` | Subido, aún no revisado. |
| IN\_REVIEW | Un usuario de Localpayment lo abrió. |
| `APPROVED` | Aceptado. Versión final para ese archivo. |
| `REJECTED` | Rechazado. Consulta verificationReason. Reemplaza el archivo cargando el mismo proofType una vez que la entidad no esté IN\_REVIEW. |

## Ciclo de vida de la prueba (status)

| Status | Significado |
| - | - |
| `CURRENT` | El archivo activo de su proofType en el documento. |
| `SUPERSEDED` | Reemplazado por una carga más reciente del mismo FRONT, BACK o SELFIE. |
| `DELETED` | Eliminado con Eliminar prueba. Conservado para auditoría. |

## Cobertura de la documentación (documentationStatus)

| Valor | Meaning |
| - | - |
| NO\_FILES | Ningún documento tiene un archivo. |
| PARTIAL | Algunos documentos tienen archivos. |
| COMPLETE | Cada documento tiene al menos un archivo. Esto no implica aprobación. |

## Formato de error

Los errores siguen la RFC 9457 (`application/problem+json`). `code` es una cadena estable y legible por máquina, `details` indica el campo que causó el error cuando corresponde, y `correlationId` identifica la solicitud: indícalo cuando te pongas en contacto con soporte.

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

Un conflicto sin detalles del 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": []
}
```

Basa tu lógica en `code`, no en `title` ni en `detail`: solo `code` tiene garantizada su estabilidad.

## Códigos de error

| HTTP | code | Causa |
| - | - | - |
| 400 | CUSTOM\_FIELDS\_INVALID | attributes no satisface tu esquema de campos personalizados. details\[] enumera el campo y el problema. |
| 400 | MISSING\_OR\_INVALID\_CLIENT\_CODE | No se pudo identificar tu cuenta comercial a partir de la solicitud. Verifica las credenciales que estás utilizando. |
| 400 | VALIDATION\_ERROR | Falta un campo, encabezado, ruta o parámetro de consulta, es desconocido o no es válido. details\[] enumera el campo y el problema. |
| 401 | MISSING\_OR\_INVALID\_ACTOR | El token de acceso no identifica al usuario que realiza la acción. |
| 401 | `UNAUTHORIZED` | Token de acceso faltante o no válido. |
| 403 | TENANT\_MISMATCH | La solicitud combina identificadores de dos cuentas comerciales. Verifica las credenciales que estás utilizando. |
| 404 | CLIENT\_NOT\_FOUND | La cuenta de comerciante que figura en tus credenciales no existe en Localpayment. |
| 404 | CUSTOM\_FIELD\_SCHEMA\_NOT\_FOUND | No se ha publicado ningún esquema de campos personalizados para tu comerciante. |
| 404 | DOCUMENT\_NOT\_FOUND | El documento no existe, fue eliminado o pertenece a otro comerciante. |
| 404 | ENTITY\_NOT\_FOUND | La entidad no existe o pertenece a otro comerciante. |
| 404 | PROOF\_NOT\_FOUND | La prueba no existe o pertenece a otro comerciante. |
| 404 | UBO\_NOT\_FOUND | El enlace UBO no existe, ya ha finalizado o pertenece a otro comerciante. |
| 409 | CONCURRENT\_MODIFICATION | Se produjeron dos cargas del mismo proofType en el mismo documento simultáneamente. Vuelve a intentar la solicitud. |
| 409 | DUPLICATE\_ENTITY | externalId, o el par tipo + id de un documento, ya existe en tu comerciante. |
| 409 | ENTITY\_IN\_REVIEW | La entidad está IN\_REVIEW: sus datos, documentos, archivos y vínculos UBO están congelados hasta que Localpayment Compliance la resuelva. |
| 409 | ENTITY\_NOT\_EDITABLE | La entidad está REJECTED, BLOCKED o CLOSED, o la operación eliminaría el documento principal o el único documento. |
| 409 | INVALID\_STATUS\_TRANSITION | La entidad no se encuentra en un estado que permita esta operación (por ejemplo, una entidad que ya está CLOSED). |
| 409 | PROOF\_APPROVED | La prueba está APPROVED: no se puede reemplazar ni eliminar. |
| 409 | PROOF\_SUPERSEDED | La prueba fue reemplazada por una carga más reciente del mismo proofType en el mismo documento. Solo se revisa la prueba activa. |
| 409 | UBO\_ALREADY\_LINKED | La persona ya tiene un vínculo UBO activo con esta empresa. |
| 409 | UBO\_LIMIT\_EXCEEDED | La empresa ya cuenta con 50 vínculos UBO activos. |
| 412 | VERSION\_CONFLICT | If-Match no coincide con la versión actual de la entidad. Lee la entidad de nuevo e inténtalo de nuevo. |
| 413 | FILE\_TOO\_LARGE | El archivo subido supera los 10 MB. |
| 413 | PAYLOAD\_TOO\_LARGE | attributes supera los 64 KB. |
| 415 | UNSUPPORTED\_FILE\_TYPE | El archivo subido no es un JPG, PNG ni PDF. |
| 415 | UNSUPPORTED\_MEDIA\_TYPE | El Content-Type de la solicitud no es el que espera el endpoint (application/json o multipart/form-data para cargas). |
| 422 | ENTITY\_NOT\_ACTIVE | La empresa (o la persona) está CLOSED, BLOCKED o REJECTED. |
| 422 | INCOMPLETE\_KYC\_DATA | Faltan los datos mínimos de KYC: nombre y apellido para INDIVIDUAL, nombre para COMPANY. |
| 422 | INVALID\_CONTROL\_ROLE | controlRole no es uno de los códigos de rol indicados en Vincular un UBO. Los códigos distinguen entre mayúsculas y minúsculas: director devuelve este error. |
| 422 | INVALID\_ENTITY\_TYPE | companyId debe ser una COMPANY y personId un INDIVIDUAL. |
| 422 | INVALID\_PERCENTAGE | ownershipPercentage está fuera del rango de 0 a 100 o tiene más de dos decimales. |
| 422 | INVALID\_VALIDITY\_RANGE | validTo es anterior a validFrom. |
| 422 | NO\_PROOFS\_UPLOADED | La entidad no tiene archivos subidos. Sube al menos un archivo antes de solicitar la verificación. |
| 502 | STORAGE\_WRITE\_FAILED | No se pudo guardar el archivo. Intenta subirlo de nuevo. |
| 503 | CLIENT\_DIRECTORY\_UNAVAILABLE | Localpayment no pudo resolver tu cuenta comercial en este momento. Inténtalo de nuevo más tarde. |

Los errores sobre tu cuenta comercial (`MISSING_OR_INVALID_CLIENT_CODE`, `CLIENT_NOT_FOUND`, `TENANT_MISMATCH`, `MISSING_OR_INVALID_ACTOR`, `CLIENT_DIRECTORY_UNAVAILABLE`) provienen de las credenciales de tu token de acceso, no del cuerpo de la solicitud. Verifica que utilizas el token de acceso de la cuenta comercial correcta y ponte en contacto con soporte con el `correlationId` si el error persiste.


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