> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Lista de errores de Pix JD
> Busca un código PIX-NNNN en el catálogo de Pix JD, la condición detrás de él y el texto detail que lleva la respuesta.
**Formato de error**
La API de Pix JD responde a una solicitud fallida con `application/problem+json`. El esquema `Detail` en esta referencia de API describe ese cuerpo, que sigue el RFC 9457.
```json JSON theme={null}
{
"type": "https://errors.lerian.studio/v1/PIX-0012",
"title": "PIX Key Not Found",
"status": 404,
"detail": "The specified PIX key was not found in the system. Please verify the key value and try again.",
"code": "PIX-0012"
}
```
**Definiciones de campos**
* **`code`** – Código de error de dominio estable y legible por máquina, con alcance limitado al servicio que lo emite. En esta API tiene la forma `PIX-NNNN`.
* **`title`** – Un resumen breve y legible por humanos del tipo de problema. Se recomienda que este valor no cambie entre apariciones del error.
* **`detail`** – Una explicación legible por humanos, específica de esta aparición del problema.
* **`status`** – El código de estado HTTP.
* **`type`** – Un URI que identifica el error en el catálogo de errores de Lerian, construido como `https://errors.lerian.studio/v1/`.
* **`instance`** – Una referencia URI que identifica la aparición específica del problema.
* **`errors`** – Una lista opcional de detalles por campo. Cada entrada lleva la `location` que falló, un `message`, y el `value` en esa ubicación.
* **`upstream`** – Un miembro de extensión de RFC 9457. Lleva el código y el mensaje que reportó un proveedor externo intermediado, y está ausente a menos que el servicio haya expuesto uno.
**Cómo leer estas tablas**
Cada fila empieza con el estado HTTP que lleva la respuesta. Luego nombra la condición. La última columna da el texto `detail` que el servicio envía por defecto. Cuando el servicio compone ese texto a partir de la solicitud que falló, la fila lo indica.
En el estado 500 y superiores, la respuesta lleva texto fijo, no la causa sin procesar. La columna `detail` muestra si un código envía `internal error` o una frase que el servicio escribió para él.
## Solicitud del servicio Pix y reglas de negocio
***
Estos códigos provienen del propio servicio Pix. Cubren la validación de solicitudes, la gestión de claves Pix, las reclamaciones de claves, las órdenes de pago, las devoluciones, los códigos QR, los participantes indirectos y los créditos entrantes.
### Validación de solicitudes y acceso
| `code` | Descripción | `detail` |
| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0001` | **400** Error de validación de campos | Uno o más campos contienen errores de validación. Revisa el objeto fields para más detalles y corrige los valores inválidos. |
| `PIX-0002` | **400** Solicitud incorrecta | Lo define la operación que generó el error. |
| `PIX-0003` | **400** Campos inesperados | Lo define la operación que generó el error. |
| `PIX-0004` | **401** No autorizado | Lo define la operación que generó el error. |
| `PIX-0005` | **403** Prohibido | Lo define la operación que generó el error. |
| `PIX-0006` | **404** No encontrado | Lo define la operación que generó el error. |
| `PIX-0007` | **409** Conflicto | Lo define la operación que generó el error. |
| `PIX-0008` | **422** Entidad no procesable | Lo define la operación que generó el error. |
| `PIX-0009` | **429** Demasiadas solicitudes | Lo define la operación que generó el error. |
| `PIX-0019` | **400** Tipo de cuenta inválido | El tipo de cuenta es inválido para esta operación. Verifica el tipo de cuenta e inténtalo de nuevo. |
| `PIX-0058` | **400** ID inválido | El ID proporcionado es inválido o tiene un formato incorrecto. Verifica el formato del ID e inténtalo de nuevo. |
| `PIX-0059` | **401** Token inválido | El token proporcionado es inválido o ha expirado. Obtén un nuevo token e inténtalo de nuevo. |
| `PIX-0060` | **400** Se requiere ubicación | La información de ubicación es obligatoria para esta operación. Proporciona datos de ubicación válidos. |
| `PIX-0061` | **400** Parámetros inválidos | Uno o más parámetros de la solicitud son inválidos. Revisa los valores de los parámetros e inténtalo de nuevo. |
| `PIX-0062` | **400** Información inválida | La información proporcionada es inválida o está incompleta. Verifica todos los campos e inténtalo de nuevo. |
| `PIX-0082` | **401** Se requiere autenticación | Se requieren credenciales de autenticación válidas para acceder a este recurso. Proporciona un token bearer válido. |
| `PIX-0083` | **403** Acceso prohibido | No tienes permisos suficientes para hacer esta acción. Contacta a soporte si crees que esto es un error. |
| `PIX-0084` | **400** Error de validación de la solicitud | La validación de la solicitud falló. Revisa todos los campos obligatorios e inténtalo de nuevo. |
### Claves Pix
| `code` | Descripción | `detail` |
| ---------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0010` | **422** Formato de clave Pix inválido | El formato de la clave PIX es inválido para el tipo especificado. Verifica que el formato coincida con el patrón esperado e inténtalo de nuevo. |
| `PIX-0011` | **409** La clave Pix ya existe | Ya existe una clave PIX con este valor. Usa una clave PIX diferente. |
| `PIX-0012` | **404** Clave Pix no encontrada | La clave PIX especificada no se encontró en el sistema. Verifica el valor de la clave e inténtalo de nuevo. |
| `PIX-0013` | **429** Límite de claves Pix superado | Alcanzaste el número máximo de claves PIX permitidas. Elimina una clave existente antes de crear una nueva. |
| `PIX-0014` | **422** Tipo de clave Pix inválido | El tipo de clave PIX no es válido para esta operación. Usa un tipo de clave admitido. |
| `PIX-0015` | **422** Clave Pix expirada | Lo define la operación que generó el error. |
| `PIX-0016` | **422** Clave Pix pendiente de confirmación | Lo define la operación que generó el error. |
| `PIX-0017` | **422** Clave Pix inactiva | Lo define la operación que generó el error. |
| `PIX-0018` | **403** No se permite eliminar la clave Pix | Esta clave PIX no está registrada a la cuenta informada, por lo que no se puede eliminar. Verifica la clave y la cuenta. |
| `PIX-0067` | **422** Clave Pix expirada | La clave PIX ha expirado y no se puede usar. Crea una nueva clave PIX. |
| `PIX-0068` | **422** Se requiere confirmación de la clave Pix | La clave PIX requiere confirmación antes de la activación. Revisa tu correo electrónico o SMS para ver el código de confirmación. |
| `PIX-0069` | **404** Clave Pix no encontrada | La clave PIX especificada no se encontró en el sistema. Verifica el valor de la clave e inténtalo de nuevo. |
| `PIX-0070` | **422** Clave Pix inválida | La clave PIX es inválida o ha sido desactivada. Usa una clave PIX válida. |
| `PIX-0071` | **409** La clave Pix ya tiene dueño | Ya eres dueño de esta clave PIX. Cada clave PIX solo puede asociarse con una cuenta. |
| `PIX-0072` | **422** Límite de claves Pix superado | Alcanzaste el número máximo de claves PIX permitidas. Elimina una clave existente antes de crear una nueva. |
| `PIX-0073` | **422** Estado de clave Pix inválido | La clave PIX no está en un estado válido para esta operación. Revisa el estado de la clave. |
| `PIX-0074` | **404** Clave Pix interna no encontrada | No se encontró la referencia interna de la clave PIX. Contacta a soporte. |
| `PIX-0086` | **422** El documento no coincide | El documento de la cuenta no coincide con el documento asociado a la clave PIX. Solo el dueño de la clave puede reclamarla. |
### Reclamaciones de claves Pix
| `code` | Descripción | `detail` |
| ---------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `PIX-0020` | **404** Reclamación no encontrada | No se encontró la reclamación especificada para esta cuenta. Verifica el ID de la reclamación e inténtalo de nuevo. |
| `PIX-0021` | **409** La reclamación ya existe | Lo define la operación que generó el error. |
| `PIX-0022` | **422** La reclamación de clave Pix o la instrucción programada está en un estado que esta acción no permite | La autorización de PIX Automatico no está en un estado válido para esta operación. Revisa el estado de la autorización. |
| `PIX-0023` | **422** Reclamación expirada | Lo define la operación que generó el error. |
| `PIX-0024` | **403** Acción no autorizada en la reclamación | Lo define la operación que generó el error. |
| `PIX-0025` | **409** La reclamación ya fue procesada | Lo define la operación que generó el error. |
| `PIX-0026` | **422** Datos de reclamación inválidos | Lo define la operación que generó el error. |
| `PIX-0027` | **400** La reclamación nombra a un participante que no coincide con el registro de la clave | Lo define la operación que generó el error. |
### Transacciones y pagos
| `code` | Descripción | `detail` |
| ---------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0028` | **404** Transacción no encontrada | Lo define la operación que generó el error. |
| `PIX-0029` | **409** Transacción duplicada | Ya existe una transacción con este identificador. Usa un ID de transacción único. |
| `PIX-0030` | **422** Monto de transacción inválido | El monto de la transacción es inválido. Proporciona un monto positivo válido. |
| `PIX-0031` | **400** Saldo insuficiente | Lo define la operación que generó el error. |
| `PIX-0032` | **409** Límite de transacción superado | Lo define la operación que generó el error. |
| `PIX-0033` | **422** Datos del destinatario inválidos | Los datos del destinatario son inválidos. Verifica toda la información del destinatario. |
| `PIX-0034` | **422** Transacción expirada | Lo define la operación que generó el error. |
| `PIX-0035` | **422** Transacción cancelada | Lo define la operación que generó el error. |
| `PIX-0036` | **422** Estado de transacción inválido | La transición de estado de la transacción no está permitida para el estado actual. |
| `PIX-0037` | **422** ID end-to-end inválido | El ID end-to-end es inválido para esta orden de pago. Revisa el valor e inténtalo de nuevo. |
| `PIX-0075` | **409** Límite de transacción superado | El monto de la transacción excede tus límites configurados. Intenta con un monto menor o contacta a soporte para aumentar tus límites. |
| `PIX-0076` | **409** Saldo insuficiente | Tu cuenta no tiene saldo suficiente para esta transacción. Agrega fondos a tu cuenta e inténtalo de nuevo. |
| `PIX-0077` | **409** No se permite transferencia al mismo Bank ID | No se permiten transferencias al mismo Bank ID para esta operación. Usa un destino diferente. |
| `PIX-0078` | **409** No se permite transferencia a la misma cuenta | No se permiten transferencias a la misma cuenta. Usa una cuenta de destino diferente. |
| `PIX-0090` | **422** Fondos insuficientes para el bloqueo | La cuenta transaccional del pagador no tiene fondos suficientes para reservar el débito programado. (SGCTPIX001) |
| `PIX-0091` | **500** Bloqueo rechazado | `internal error` |
### Devoluciones y reembolsos
| `code` | Descripción | `detail` |
| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `PIX-0038` | **403** No se permite la devolución | Lo define la operación que generó el error. |
| `PIX-0039` | **422** Motivo de devolución inválido | Lo define la operación que generó el error. |
| `PIX-0040` | **422** El monto de la devolución excede el original | Lo define la operación que generó el error. |
| `PIX-0041` | **403** Ventana de devolución expirada | Lo define la operación que generó el error. |
| `PIX-0042` | **404** Transacción original no encontrada | Lo define la operación que generó el error. |
| `PIX-0087` | **400** No puedes reembolsar tu propia transacción | No puedes solicitar un reembolso de tu propia transacción saliente. Solo el destinatario puede solicitar un reembolso. |
| `PIX-0088` | **400** No puedes reembolsar una transacción no recibida | Solo puedes solicitar reembolsos de transacciones que hayas recibido. |
| `PIX-0089` | **400** No puedes reembolsar una transacción saliente | Las transacciones salientes (CASH\_OUT) no se pueden reembolsar. Solo se pueden reembolsar las transacciones recibidas. |
### Participantes y cuentas
| `code` | Descripción | `detail` |
| ---------- | --------------------------------- | ------------------------------------------- |
| `PIX-0043` | **422** Bank ID inválido | Lo define la operación que generó el error. |
| `PIX-0044` | **422** Bank ID no participante | Lo define la operación que generó el error. |
| `PIX-0045` | **422** Número de cuenta inválido | Lo define la operación que generó el error. |
| `PIX-0046` | **422** Cuenta bloqueada | Lo define la operación que generó el error. |
| `PIX-0047` | **422** Cuenta cerrada | Lo define la operación que generó el error. |
### Códigos QR
| `code` | Descripción | `detail` |
| ---------- | -------------------------- | ------------------------------------------- |
| `PIX-0048` | **422** Código QR inválido | Lo define la operación que generó el error. |
| `PIX-0049` | **504** Código QR expirado | `internal error` |
| `PIX-0050` | **422** Código QR ya usado | Lo define la operación que generó el error. |
### Entidades, plantillas y conciliación
| `code` | Descripción | `detail` |
| ---------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `PIX-0063` | **404** Entidad no encontrada | La entidad especificada no se encontró en el sistema. Verifica el identificador e inténtalo de nuevo. |
| `PIX-0064` | **409** La entidad ya existe | Ya existe una entidad con este identificador. Usa un identificador único. |
| `PIX-0065` | **409** El ID de conciliación ya existe | Ya existe un registro con este ID de conciliación. Usa un ID de conciliación único. |
| `PIX-0066` | **404** Plantilla no encontrada | No se encontró la plantilla especificada. Verifica el identificador de la plantilla. |
| `PIX-0110` | **409** La entidad ya fue retirada | La entidad especificada ya fue retirada y ya no se puede actuar sobre ella. |
### Fraude, cumplimiento y regulación
| `code` | Descripción | `detail` |
| ---------- | ---------------------------------- | ------------------------------------------- |
| `PIX-0055` | **400** Fraude detectado | Lo define la operación que generó el error. |
| `PIX-0056` | **403** Infracción de cumplimiento | Lo define la operación que generó el error. |
| `PIX-0057` | **403** Restricción regulatoria | Lo define la operación que generó el error. |
### Fallas de servicio y de dependencias
| `code` | Descripción | `detail` |
| ---------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `PIX-0051` | **503** Servicio no disponible | La integración PIX no está disponible temporalmente para este tenant. Inténtalo de nuevo en breve. |
| `PIX-0052` | **504** Timeout | `internal error` |
| `PIX-0053` | **500** Error interno | `internal error` |
| `PIX-0054` | **502** Error de servicio externo | `internal error` |
| `PIX-0079` | **502** Error de servicio externo | `internal error` |
| `PIX-0080` | **500** Error de core banking | `internal error` |
| `PIX-0085` | **500** Error de conexión con la base de datos | `internal error` |
| `PIX-0109` | **500** Falla del servidor que el servicio no pudo atribuir a una condición específica | `internal error` |
### Configuración del tenant
| `code` | Descripción | `detail` |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0092` | **409** Integración Pix del tenant no aprovisionada | La integración PIX para este tenant no ha sido aprovisionada. Contacta a soporte para completar el onboarding del tenant. |
| `PIX-0105` | **409** Falta la configuración de ruta del tenant | La configuración de enrutamiento PIX para este tenant falta o es inválida. Contacta a soporte para completar el onboarding del tenant. |
| `PIX-0106` | **409** Falta la configuración del ledger del tenant | La identidad del ledger de Midaz para este tenant no está aprovisionada, así que no se registró ninguna transacción. Deben estar configurados tanto el activo de contabilización como la cuenta de compensación externa: en modo multi-tenant, las claves systemplane tenant\_policy/midaz.asset\_id y tenant\_policy/midaz.external\_id, y en modo de tenant único, los valores de despliegue MIDAZ\_ASSET\_ID y MIDAZ\_EXTERNAL\_ID. Solo un operador puede proporcionarlos, así que repetir esta solicitud sin ese cambio fallará de forma idéntica. |
| `PIX-0107` | **409** Cifrado de entrega indirecta no aprovisionado. Se genera cuando la clave de cifrado del secreto de entrega del tenant está ausente, en blanco o mal formada, y cuando no hay ningún cifrador configurado. La ausencia y el formato incorrecto comparten este código porque comparten la solución: un operador cambia el valor. En modo de tenant único, ese valor es `INDIRECTS_DELIVERY_ENCRYPTION_KEY`, y debe tener exactamente 64 caracteres hexadecimales (una clave AES-256 codificada en hexadecimal) | No hay ninguna clave de cifrado del secreto de entrega aprovisionada para este tenant, así que el participante indirecto no se guardó y no se almacenó ningún secreto. Los despliegues de tenant único configuran INDIRECTS\_DELIVERY\_ENCRYPTION\_KEY; los despliegues multi-tenant aprovisionan la clave de cifrado del secreto de entrega de este tenant en el almacén de secretos del despliegue. Solo un operador puede proporcionarla, así que repetir esta solicitud sin ese cambio fallará de forma idéntica. |
| `PIX-0108` | **422** Alias de cuenta del ledger no resuelto | Lo define la operación que generó el error. |
| `PIX-0121` | **409** ISPB de la integración Pix del tenant inválido | La integración PIX para este tenant está mal configurada: el campo "ispb" de la clave systemplane tenancy/jd\_integration\_binding debe tener exactamente 8 dígitos. Contacta a soporte para corregir el binding de integración PIX del tenant. |
| `PIX-0122` | **503** Configuración del ledger del tenant ilegible | No se pudo leer la identidad del ledger de Midaz para este tenant desde el plano de configuración del tenant, así que no se registró ninguna transacción. No se sabe que la configuración esté ausente, la lectura en sí no se completó, así que esta es una falla de nuestro lado y no un vacío de onboarding. Inténtalo de nuevo en breve; si persiste, contacta a soporte. |
| `PIX-0123` | **503** Fuente de la clave de entrega indirecta no disponible | No se pudo leer la clave de cifrado del secreto de entrega de este tenant desde su fuente de claves, así que el participante indirecto no se guardó y no se almacenó ningún secreto. No se sabe que la clave esté ausente, la lectura en sí no se completó, así que esta es una falla de nuestro lado y no un vacío de onboarding. Inténtalo de nuevo en breve; si persiste, contacta a soporte. |
**Si conviene reintentar lo decide el estado, no la familia.** Un `409` en esta sección es un vacío de aprovisionamiento: se sabe que el valor está ausente, solo un operador puede proporcionarlo, y repetir la solicitud no puede cambiar eso. Un `503` es la hermana *ilegible* de la misma condición: **no** se sabe que la configuración esté ausente, la lectura en sí no se completó, así que nombra la dependencia que falló y vale la pena reintentarlo.
Los pares son `PIX-0092`/`PIX-0121` frente a `PIX-0051`, `PIX-0106` frente a `PIX-0122`, y `PIX-0107` frente a `PIX-0123`.
### Participantes indirectos
| `code` | Descripción | `detail` |
| ---------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0093` | **409** Conflicto de ISPB indirecto | Ya hay un participante indirecto con este ISPB registrado y activo para este tenant. Un indirecto cerrado puede volver a registrarse, pero uno abierto es único por ISPB. |
| `PIX-0094` | **409** Transición indirecta no permitida | El cambio de ciclo de vida solicitado no está permitido para el estado actual del participante indirecto. |
| `PIX-0095` | **404** Indirecto no encontrado | No se encontró el participante indirecto especificado para este tenant. Verifica el identificador e inténtalo de nuevo. |
| `PIX-0096` | **409** No se puede cerrar un indirecto con saldo | El participante indirecto no se puede cerrar mientras su cuenta PIX mantenga fondos. Liquida el saldo disponible y el monto retenido a cero e inténtalo de nuevo. |
| `PIX-0097` | **409** El indirecto no está a la espera de aprovisionamiento | El reintento de aprovisionamiento solo es válido para un participante indirecto en el estado PENDING\_PROVISIONING. |
| `PIX-0098` | **422** Participante indirecto inválido | La solicitud de participante indirecto es inválida. Verifica el nombre, el ISPB, el endpoint de entrega, el secret y el modo de mensajería, e inténtalo de nuevo. |
| `PIX-0099` | **502** Falló el aprovisionamiento del indirecto | `internal error` |
| `PIX-0100` | **422** Indirecto no activo | El participante indirecto especificado no está activo y no puede originar una transacción. Reactívalo e inténtalo de nuevo. |
| `PIX-0102` | **422** El pagador no coincide con el indirecto | El ISPB del pagador proporcionado no coincide con el participante indirecto resuelto. Verifica el identificador del indirecto y los datos del pagador, e inténtalo de nuevo. |
| `PIX-0103` | **409** El estacionamiento del crédito no está abierto | El crédito entrante estacionado ya no está en PARKED (ya fue resuelto o rechazado, posiblemente por una solicitud concurrente). No se tomó ninguna otra acción. |
| `PIX-0104` | **409** El indirecto de destino no está activo | El participante indirecto al que apunta esta resolución no está en ACTIVE y no puede recibir el crédito. Reactívalo o elige un destino diferente. |
| `PIX-0111` | **422** Función de indirectos deshabilitada | Lo define la operación que generó el error. |
| `PIX-0112` | **422** Ubicación del QR del indirecto demasiado larga | Lo define la operación que generó el error. |
| `PIX-0113` | **422** Host del QR del indirecto no público | Lo define la operación que generó el error. |
| `PIX-0114` | **422** El indirecto no tiene certificado QR propio | Lo define la operación que generó el error. |
### Créditos entrantes
| `code` | Descripción | `detail` |
| ---------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-0115` | **404** Cuenta de cash-in no encontrada | La cuenta receptora nombrada por este crédito no se encontró en este participante, así que no se registró ningún crédito. |
| `PIX-0116` | **409** Destino del cash-in ambiguo | El documento del receptor nombra más de una cuenta en este participante, así que no se puede determinar el destino de este crédito. No se registró ningún crédito. Dirige el crédito a una cuenta específica (recebedor.nrAgencia y recebedor.nrConta) o contacta a este participante para que corrijan los registros duplicados. |
| `PIX-0117` | **409** El titular del cash-in no coincide | La cuenta a la que se dirige este crédito pertenece a un titular diferente del que nombra el documento del receptor, así que no se registró ningún crédito. Verifica recebedor.cpfCnpj contra recebedor.nrAgencia y recebedor.nrConta. |
| `PIX-0118` | **409** La cuenta de cash-in no admite créditos | La cuenta a la que se dirige este crédito existe en este participante, pero no está configurada para recibir créditos, así que no se registró ningún crédito. Contacta a este participante para que completen el registro de la cuenta. |
| `PIX-0119` | **404** Receptor del cash-in no atendido | El participante receptor nombrado por este crédito no es atendido por este participante, así que no se registró ningún crédito. Verifica recebedor.ispb. |
| `PIX-0120` | **500** Ledger del cash-in mal aprovisionado | `internal error` |
## Riel Pix y directorio de claves
***
Estos códigos provienen de la infraestructura Pix conectada. El servicio traduce una falla del riel a uno de estos códigos antes de responder. Quien llama ramifica su lógica según un valor `PIX-NNNN`, no según el vocabulario propio del riel.
### Validación de solicitudes y autenticación
| `code` | Descripción | `detail` |
| ---------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `PIX-1000` | **400** Error de validación de campos | Uno o más campos contienen errores de validación. Revisa el objeto fields para más detalles y corrige los valores inválidos. |
| `PIX-1001` | **400** Solicitud incorrecta | El servidor no pudo entender la solicitud debido a una sintaxis mal formada. Revisa el formato de la solicitud e inténtalo de nuevo. |
| `PIX-1002` | **400** Campos inesperados en la solicitud | El cuerpo de la solicitud contiene más campos de los esperados. Envía solo los campos permitidos según la documentación. |
| `PIX-1003` | **401** No autorizado | Las credenciales de autenticación faltaban o eran incorrectas. Proporciona credenciales válidas. |
| `PIX-1004` | **403** Prohibido | El servidor entendió la solicitud pero se niega a autorizarla. Revisa tus permisos. |
| `PIX-1005` | **404** No encontrado | No se encontró el recurso solicitado. Verifica el identificador e inténtalo de nuevo. |
| `PIX-1006` | **409** Conflicto | La solicitud no se pudo completar debido a un conflicto con el estado actual. |
| `PIX-1007` | **422** Entidad no procesable | La solicitud tenía un formato correcto, pero no se pudo procesar debido a errores semánticos. |
| `PIX-1008` | **429** Demasiadas solicitudes | Se enviaron demasiadas solicitudes. Espera antes de hacer otra solicitud. |
| `PIX-1059` | **400** Falta el token de autenticación | Falta el token de autenticación en la solicitud. Proporciona un token Bearer válido en el header Authorization. |
| `PIX-1060` | **400** Token de autenticación inválido | El token de autenticación proporcionado es inválido. Obtén un nuevo token e inténtalo de nuevo. |
| `PIX-1061` | **400** Token de autenticación expirado | El token de autenticación ha expirado. Obtén un nuevo token usando el endpoint de autenticación. |
| `PIX-1062` | **400** Permisos insuficientes | El participante autenticado no tiene permisos suficientes para hacer esta operación. |
| `PIX-1063` | **400** Participante no autorizado | El participante autenticado no está autorizado para hacer esta operación en el recurso especificado. |
| `PIX-1064` | **400** Se violó una regla de autenticación o autorización | La solicitud viola reglas de autenticación o autorización. Verifica tus credenciales y permisos. |
### Claves Pix
| `code` | Descripción | `detail` |
| ---------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-1009` | **422** Formato de clave Pix inválido | El formato de la clave PIX es inválido para el tipo especificado. Verifica que el formato coincida con el patrón esperado e inténtalo de nuevo. |
| `PIX-1010` | **409** La clave Pix ya existe | Ya existe una clave PIX con este valor. Usa una clave PIX diferente. |
| `PIX-1011` | **404** Clave Pix no encontrada | La clave PIX especificada no se encontró en el sistema. Verifica el valor de la clave e inténtalo de nuevo. |
| `PIX-1012` | **400** Límite de claves Pix superado | Alcanzaste el número máximo de claves PIX permitidas. Elimina una clave existente antes de crear una nueva. |
| `PIX-1013` | **422** Tipo de clave Pix inválido | El tipo de clave PIX es inválido. Usa un tipo de clave PIX válido. |
| `PIX-1014` | **422** Clave Pix expirada | La clave PIX ha expirado y no se puede usar. Crea una nueva clave PIX. |
| `PIX-1015` | **400** Clave Pix pendiente de confirmación | La clave PIX está pendiente de confirmación. Completa el proceso de confirmación. |
| `PIX-1016` | **400** Clave Pix inactiva | La clave PIX está inactiva y no se puede usar. Activa la clave PIX. |
| `PIX-1017` | **403** No se permite eliminar la clave Pix | La clave PIX no se puede eliminar en su estado actual. Revisa el estado de la clave. |
| `PIX-1018` | **422** Tipo de cuenta inválido | El tipo de cuenta es inválido para esta operación. Usa un tipo de cuenta válido. |
### Reclamaciones de claves Pix
| `code` | Descripción | `detail` |
| ---------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `PIX-1019` | **404** Reclamación de clave Pix no encontrada | No se encontró la reclamación de clave PIX especificada. Verifica el identificador de la reclamación. |
| `PIX-1020` | **409** La reclamación de clave Pix ya existe | Ya existe una reclamación de clave PIX con este identificador. Usa un identificador único. |
| `PIX-1021` | **422** Estado de reclamación inválido | La reclamación no está en un estado válido para esta operación. Revisa el estado de la reclamación. |
| `PIX-1022` | **422** Reclamación de clave Pix expirada | La reclamación de clave PIX ha expirado y no se puede procesar. Crea una nueva reclamación. |
| `PIX-1023` | **403** Acción no autorizada en la reclamación | No estás autorizado para hacer esta acción en la reclamación. Revisa tus permisos. |
| `PIX-1024` | **409** La reclamación ya fue procesada | La reclamación de clave PIX ya fue procesada y no se puede modificar. |
| `PIX-1025` | **422** Datos de reclamación inválidos | Los datos de la reclamación proporcionados son inválidos. Verifica todos los campos e inténtalo de nuevo. |
| `PIX-1026` | **400** El Bank ID de la reclamación no coincide | Hay una discrepancia de Bank ID en la solicitud de reclamación. Verifica los valores de Bank ID. |
### Transacciones y pagos
| `code` | Descripción | `detail` |
| ---------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `PIX-1027` | **404** Transacción no encontrada | No se encontró la transacción especificada. Verifica el identificador de la transacción. |
| `PIX-1028` | **409** La transacción ya existe | Ya existe una transacción con este identificador. Usa un ID de transacción único. |
| `PIX-1029` | **422** Monto de transacción inválido | El monto de la transacción es inválido. Proporciona un monto positivo válido. |
| `PIX-1030` | **400** Saldo insuficiente | La cuenta no tiene saldo suficiente para esta transacción. Agrega fondos e inténtalo de nuevo. |
| `PIX-1031` | **409** Límite de transacción superado | El monto de la transacción excede los límites configurados. Intenta con un monto menor. |
| `PIX-1032` | **422** Datos del destinatario inválidos | Los datos del destinatario son inválidos. Verifica toda la información del destinatario. |
| `PIX-1033` | **422** Transacción expirada | La transacción ha expirado y no se puede procesar. Crea una nueva transacción. |
| `PIX-1034` | **422** Transacción cancelada | La transacción fue cancelada y no se puede procesar. |
| `PIX-1035` | **422** Falló la validación del pago | La validación del pago falló. Verifica todos los detalles del pago e inténtalo de nuevo. |
| `PIX-1036` | **400** ID end-to-end inválido | El formato del ID end-to-end es inválido. Usa un identificador end-to-end válido. |
### Devoluciones
| `code` | Descripción | `detail` |
| ---------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `PIX-1037` | **400** No se permite la devolución | No se permite la devolución para esta transacción. Revisa el estado de la transacción y la elegibilidad para devolución. |
| `PIX-1038` | **422** Motivo de devolución inválido | El código de motivo de devolución es inválido. Usa un código de motivo de devolución válido. |
| `PIX-1039` | **422** El monto de la devolución excede el original | El monto de la devolución excede el monto de la transacción original. Ingresa un monto de devolución válido. |
| `PIX-1040` | **400** Ventana de devolución expirada | La ventana de devolución expiró para esta transacción. Ya no se permiten devoluciones. |
| `PIX-1041` | **404** Transacción original no encontrada | No se encontró la transacción original para esta devolución. Verifica el identificador de la transacción. |
### Participantes y cuentas
| `code` | Descripción | `detail` |
| ---------- | --------------------------------- | ------------------------------------------------------------------------------------ |
| `PIX-1042` | **422** Bank ID inválido | El código de Bank ID es inválido. Proporciona un código de Bank ID válido. |
| `PIX-1043` | **422** Bank ID no participante | El Bank ID no participa en el sistema PIX. Usa un Bank ID participante. |
| `PIX-1044` | **422** Número de cuenta inválido | El formato del número de cuenta es inválido. Proporciona un número de cuenta válido. |
| `PIX-1045` | **422** Cuenta bloqueada | La cuenta está bloqueada y no se puede acceder a ella. Contacta a soporte. |
| `PIX-1046` | **400** Cuenta cerrada | La cuenta está cerrada y no se puede acceder a ella. Usa una cuenta activa. |
### Códigos QR
| `code` | Descripción | `detail` |
| ---------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `PIX-1047` | **422** Código QR inválido | El formato del código QR es inválido o está corrupto. Verifica el código QR e inténtalo de nuevo. |
| `PIX-1048` | **404** Código QR expirado | El código QR expiró y no se puede usar. Genera un nuevo código QR. |
| `PIX-1049` | **422** Código QR ya usado | El código QR ya fue usado y no se puede volver a usar. |
### Disponibilidad del riel
| `code` | Descripción | `detail` |
| ---------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `PIX-1050` | **503** Servicio JDPI no disponible | El servicio JDPI no está disponible temporalmente. Inténtalo de nuevo más tarde. |
| `PIX-1051` | **504** Timeout del servicio JDPI | La solicitud al servicio JDPI agotó el tiempo de espera. Inténtalo de nuevo. |
| `PIX-1052` | **500** Error interno de JDPI | Ocurrió un error interno de JDPI. Contacta a soporte si el problema persiste. |
| `PIX-1053` | **429** Demasiadas solicitudes | Se enviaron demasiadas solicitudes. Espera antes de hacer otra solicitud. |
| `PIX-1054` | **400** Error de conexión con JDPI | No se pudo conectar con el servicio JDPI. Revisa la disponibilidad del servicio e inténtalo de nuevo. |
| `PIX-1055` | **502** Error de servicio externo | `internal error` |
### Fraude, cumplimiento y regulación
| `code` | Descripción | `detail` |
| ---------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |
| `PIX-1056` | **403** Fraude detectado | La transacción fue bloqueada por detección de fraude. Contacta a soporte. |
| `PIX-1057` | **403** Infracción de cumplimiento | Se detectó una infracción de cumplimiento. Confirma que se cumplan todos los requisitos. |
| `PIX-1058` | **403** Restricción regulatoria | Una restricción regulatoria aplica a esta operación. Contacta a soporte. |
## Fallas que se originan fuera del riel Pix
***
Una solicitud Pix también puede fallar porque otro servicio de la plataforma la rechazó. Tres bandas de códigos llevan esos rechazos: los registros de clientes, la autorización y el ledger de Midaz.
### Registros de clientes
| `code` | Descripción | `detail` |
| ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `PIX-2000` | **422** Anidamiento de metadatos inválido | El objeto metadata no puede contener valores anidados. Verifica que el valor no esté anidado e inténtalo de nuevo. |
| `PIX-2001` | **422** Clave de metadatos demasiado larga | La clave de metadatos excede la longitud máxima permitida. Usa un nombre de clave más corto. |
| `PIX-2002` | **400** Faltan campos en la solicitud | A tu solicitud le faltan uno o más campos obligatorios. Proporciona todos los campos obligatorios e inténtalo de nuevo. |
| `PIX-2003` | **400** Tipo de campo inválido en la solicitud | Uno o más campos tienen tipos de datos incorrectos. Revisa los tipos de campo e inténtalo de nuevo. |
| `PIX-2004` | **400** Parámetro de ruta inválido | Los parámetros de ruta tienen un formato incorrecto. Verifica el formato del parámetro. |
| `PIX-2005` | **400** Campos inesperados en la solicitud | La solicitud contiene más campos de los esperados. Envía solo los campos permitidos según la documentación. |
| `PIX-2006` | **422** Límite de paginación superado | El límite de paginación excede el valor máximo permitido. Usa un límite menor. |
| `PIX-2007` | **400** Orden de clasificación inválido | El orden de clasificación debe ser "asc" o "desc". Usa un orden de clasificación válido. |
| `PIX-2008` | **400** Valor de metadatos demasiado largo | El valor de metadatos excede la longitud máxima permitida. Usa un valor más corto. |
| `PIX-2009` | **409** La cuenta ya está asociada | La cuenta solo puede asociarse con una cuenta relacionada. Usa una cuenta diferente. |
| `PIX-2010` | **400** Solicitud incorrecta | El servidor no puede entender la solicitud debido a una sintaxis inválida. Revisa el formato de la solicitud. |
| `PIX-2011` | **400** Parámetro de query string inválido | Los parámetros de query string tienen un formato incorrecto. Verifica los valores de los parámetros. |
| `PIX-2012` | **422** No se puede eliminar el titular | El titular no se puede eliminar debido a cuentas asociadas. Elimina primero las cuentas asociadas. |
| `PIX-2013` | **400** Faltan headers en la solicitud | A la solicitud le faltan parámetros de header obligatorios. Incluye todos los headers obligatorios. |
| `PIX-2014` | **400** Formato de metadatos inválido | El formato del parámetro metadata es incorrecto. Usa el formato de metadatos correcto. |
| `PIX-2015` | **404** ID de titular no encontrado | El ID de titular especificado no existe. Verifica el ID de titular e inténtalo de nuevo. |
| `PIX-2016` | **404** ID de cuenta no encontrado | El ID de cuenta especificado no existe. Verifica el ID de cuenta e inténtalo de nuevo. |
| `PIX-2017` | **403** Falló la autenticación del CRM | La autenticación del CRM falló. Verifica tus credenciales. |
| `PIX-2018` | **409** Error de asociación de documento | El documento solo puede asociarse con un titular. Usa un documento diferente. |
| `PIX-2019` | **500** Error interno del servidor | `internal error` |
| `PIX-2020` | **503** Error de conexión con el CRM | `internal error` |
| `PIX-2021` | **504** Timeout del servicio CRM | `internal error` |
| `PIX-2022` | **503** Servicio CRM no disponible | `internal error` |
| `PIX-2023` | **401** Falló la autenticación del CRM | La autenticación del CRM falló. Verifica tus credenciales. |
| `PIX-2024` | **429** Rate limit del CRM superado | Se superó el rate limit del servicio CRM. Espera antes de hacer otra solicitud. |
### Autorización
| `code` | Descripción | `detail` |
| ---------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `PIX-3000` | **400** Faltan campos en la solicitud | A tu solicitud le faltan uno o más campos obligatorios. Proporciona todos los campos obligatorios e inténtalo de nuevo. |
| `PIX-3001` | **422** Grant type inválido | El grant type proporcionado es inválido. Usa "client\_credentials" para la autenticación. |
| `PIX-3002` | **422** Faltan campos para el grant type | Faltan campos obligatorios para el grant type. Proporciona client\_id y client\_secret. |
| `PIX-3003` | **422** Grant type no admitido | La aplicación no admite este grant type. Usa "client\_credentials". |
| `PIX-3004` | **401** Cliente inválido | Las credenciales de cliente proporcionadas son inválidas. Verifica tu client ID y client Secret. |
| `PIX-3005` | **400** Solicitud incorrecta | El servidor no puede entender la solicitud debido a una sintaxis inválida. Revisa el formato de la solicitud. |
| `PIX-3006` | **400** Error de conexión con Access Manager | No se pudo conectar con el servicio Access Manager. Revisa la disponibilidad del servicio e inténtalo de nuevo. |
| `PIX-3007` | **504** Timeout de Access Manager | `internal error` |
| `PIX-3008` | **503** Servicio Access Manager no disponible | `internal error` |
### Ledger
| `code` | Descripción | `detail` |
| ---------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `PIX-4000` | **503** Error de conexión con Midaz | `internal error` |
| `PIX-4001` | **504** Timeout del servicio Midaz | `internal error` |
| `PIX-4002` | **503** Servicio Midaz no disponible | `internal error` |
| `PIX-4003` | **401** Falló la autenticación de Midaz | La autenticación de Midaz falló. Verifica tus credenciales. |
| `PIX-4004` | **403** Acceso no autorizado a Midaz | Acceso no autorizado al servicio Midaz. Revisa tus permisos. |
| `PIX-4005` | **400** Solicitud a Midaz inválida | Solicitud inválida al servicio Midaz. Verifica el formato de la solicitud. |
| `PIX-4006` | **404** Cuenta de Midaz no encontrada | No se encontró la cuenta de Midaz especificada. Verifica el ID de la cuenta e inténtalo de nuevo. |
| `PIX-4007` | **422** Cuenta de Midaz bloqueada | La cuenta de Midaz está bloqueada y no se puede acceder a ella. Contacta a soporte. |
| `PIX-4008` | **400** Cuenta de Midaz cerrada | La cuenta de Midaz está cerrada y no se puede acceder a ella. Contacta a soporte. |
| `PIX-4009` | **422** Saldo de Midaz insuficiente | La cuenta no tiene saldo suficiente para esta operación. Agrega fondos e inténtalo de nuevo. |
| `PIX-4010` | **503** Error al obtener el saldo de Midaz | `internal error` |
| `PIX-4011` | **500** Falló la transacción de Midaz | `internal error` |
| `PIX-4012` | **500** Falló el débito de Midaz | `internal error` |
| `PIX-4013` | **500** Falló el crédito de Midaz | `internal error` |
| `PIX-4014` | **404** Transacción de Midaz no encontrada | No se encontró la transacción de Midaz especificada. Verifica el ID de la transacción. |
| `PIX-4015` | **409** Transacción de Midaz duplicada | Ya existe una transacción de Midaz con este identificador. Usa un ID de transacción único. |
| `PIX-4016` | **422** Monto de transacción inválido | El monto de la transacción es inválido. Proporciona un monto positivo válido. |
| `PIX-4017` | **409** Límite de transacción de Midaz superado | El monto de la transacción excede los límites configurados en Midaz. Intenta con un monto menor. |
## Entrega de notificaciones
***
Los flujos de propiedad de claves Pix envían un código de un solo uso por correo electrónico o por SMS. Estos códigos reportan una falla en ese tramo de entrega.
### Entrega por correo electrónico
| `code` | Descripción | `detail` |
| ---------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `PIX-5000` | **401** API key inválida | La API key de SendGrid es inválida, fue eliminada, o los permisos cambiaron. Verifica tu API key. |
| `PIX-5001` | **400** Payload mal formado | La solicitud de payload de la API de SendGrid está mal formada. Revisa el formato de la solicitud. |
| `PIX-5002` | **403** Permisos insuficientes | No tienes permisos suficientes para esta operación de SendGrid. Revisa los permisos de tu cuenta. |
| `PIX-5003` | **429** Rate limit superado | Se superó el rate limit de SendGrid. Espera antes de hacer otra solicitud. |
| `PIX-5004` | **400** Error de conexión con SendGrid | No se pudo conectar con el servicio de correo electrónico de SendGrid. Revisa la disponibilidad del servicio e inténtalo de nuevo. |
| `PIX-5005` | **504** Timeout del servicio SendGrid | La solicitud al servicio de correo electrónico de SendGrid agotó el tiempo de espera. Inténtalo de nuevo. |
| `PIX-5006` | **503** Servicio SendGrid no disponible | El servicio de correo electrónico de SendGrid no está disponible temporalmente. Inténtalo de nuevo más tarde. |
### Entrega por SMS
| `code` | Descripción | `detail` |
| ---------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `PIX-6000` | **403** Permiso denegado | Permiso denegado para la operación de SMS de Twilio. Revisa los permisos de tu cuenta e inténtalo de nuevo. |
| `PIX-6001` | **401** Token de acceso inválido | El token de acceso de Twilio es inválido. Verifica tus credenciales de autenticación. |
| `PIX-6002` | **401** Falló la autenticación | La autenticación de SMS de Twilio falló. Verifica las credenciales de tu cuenta. |
| `PIX-6003` | **400** Limitación de cuenta de prueba | Esta función no está disponible para cuentas de prueba. Actualiza tu cuenta de Twilio. |
| `PIX-6004` | **400** Formato de URL inválido | Formato de URL inválido para el webhook de Twilio. Verifica el formato de la URL e inténtalo de nuevo. |
| `PIX-6005` | **400** Infracción del protocolo HTTP | Infracción del protocolo HTTP en la solicitud de Twilio. Revisa el formato de la solicitud. |
| `PIX-6006` | **429** Rate limit de SMS superado | Se superó el rate limit de envío de SMS de Twilio. Espera antes de enviar más mensajes. |
| `PIX-6007` | **400** El teléfono no admite SMS | El número de teléfono de origen no admite SMS. Usa un número de teléfono que admita SMS. |
| `PIX-6008` | **400** Límite de respuestas superado | Se superó el límite de mensajes de respuesta de TwiML. Reduce el número de mensajes de respuesta. |
| `PIX-6009` | **400** El verbo usado para la solicitud de SMS no está permitido | Verbo inválido para la respuesta de SMS. Usa un verbo de TwiML válido. |
| `PIX-6010` | **400** Teléfono inválido para prueba | Número de teléfono de destino inválido para el modo de prueba. Verifica el número o actualiza tu cuenta. |
| `PIX-6011` | **400** El número de teléfono del remitente no está verificado | El número de teléfono de origen no está verificado para tu cuenta de Twilio. Verifica el número. |
| `PIX-6012` | **400** El número de teléfono del remitente no está verificado | El número de teléfono de origen no está verificado para tu cuenta de Twilio. Verifica el número. |
| `PIX-6013` | **400** Número de teléfono de destino inválido | El formato del número de teléfono de destino es inválido. Usa un número de teléfono válido. |
| `PIX-6014` | **400** Número de teléfono del remitente inválido | El formato del número de teléfono del remitente es inválido. Usa un número de teléfono válido. |
| `PIX-6015` | **400** Error de conexión con Twilio | No se pudo conectar con el servicio de SMS de Twilio. Revisa la disponibilidad del servicio e inténtalo de nuevo. |
| `PIX-6016` | **504** Timeout del servicio Twilio | La solicitud al servicio de SMS de Twilio agotó el tiempo de espera. Inténtalo de nuevo. |
| `PIX-6017` | **503** Servicio Twilio no disponible | El servicio de SMS de Twilio no está disponible temporalmente. Inténtalo de nuevo más tarde. |
## Motivos de rechazo de devolución MED
***
Una solicitud de reembolso MED que este participante analiza y rechaza lleva un motivo de rechazo numerado. El dominio usa los valores 0, 1, 3 y 4.
| Valor | Etiqueta | Qué significa |
| ----- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `0` | Falta de saldo | La cuenta del cliente no tiene el saldo para financiar el reembolso. |
| `1` | Relacionamento encerrado | La relación con el cliente está cerrada. |
| `3` | Generico | Un motivo que los otros tres valores no cubren. |
| `4` | Requisicao invalida | La solicitud de reembolso es inválida. Este valor aplica cuando el motivo del reembolso es una falla operativa. |
## Códigos de motivo de devolución Pix
***
Un Pix devuelto lleva un motivo de devolución de Bacen propio, separado de los códigos `PIX-NNNN` anteriores. Esta referencia de API documenta los valores permitidos en el campo que los lleva. Ese campo es `codigoDevolucao` en un crédito entrante y en la vista de estado del crédito de reembolso. En una solicitud de reembolso es `code`.