application/problem+json. El esquema Detail en esta referencia de API describe ese cuerpo, que sigue el RFC 9457.
{
"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"
}
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 formaPIX-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 comohttps://errors.lerian.studio/v1/<code>.instance– Una referencia URI que identifica la aparición específica del problema.errors– Una lista opcional de detalles por campo. Cada entrada lleva lalocationque falló, unmessage, y elvalueen 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.
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.