Errores en dispersiones BRE-B

A continuación se documentan los códigos de error específicos que pueden presentarse al interactuar con los endpoints de dispersiones BRE-B (previsualización y creación de pagos).

Formato de error

Las respuestas de error siguen esta estructura:

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "EXC_033",
  "message": "El valor de la llave BRE-B no tiene un formato válido.",
  "type": "Business"
}

Campo	Descripción
status	Código de estado HTTP
meta.trace_id	Identificador único de la solicitud para trazabilidad
code	Código interno del error
message	Descripción legible del error
type	Clasificación: Business (regla de negocio) o Technical (error técnico)

Errores de previsualización

Errores que se presentan al resolver una llave BRE-B con el endpoint GET /v2/breb/keys/resolve/{keyValue}.

Código	HTTP	Tipo	Mensaje	Acción recomendada
EXC_033	400	Business	El valor de la llave BRE-B no tiene un formato válido.	Verificar que el valor de la llave cumple el formato esperado según su tipo (ver tabla de formatos abajo)
EXC_034	404	Business	La llave BRE-B no se encuentra activa o no está registrada.	Confirmar con el beneficiario que la llave está registrada y activa en su entidad financiera
EXC_035	400	Business	La llave BRE-B existe pero no está activa.	La llave está registrada pero fue desactivada. El beneficiario debe reactivarla en su entidad financiera
EXC_036	503	Technical	El servicio de resolución BRE-B no está disponible.	Reintentar después de unos segundos. Si persiste, contactar soporte
EXC_037	503	Technical	Tiempo de espera agotado al resolver la llave BRE-B.	Reintentar después de unos segundos. Si persiste, contactar soporte

Errores de creación de dispersión

Errores que se presentan al crear un lote con el endpoint POST /v2/payouts.

Código	HTTP	Tipo	Mensaje	Acción recomendada
EXC_001	500	Technical	Se presentó error interno procesando la solicitud.	Reintentar la solicitud. Si persiste, contactar soporte con el trace_id
EXC_008	400	Business	Saldo insuficiente para procesar el lote.	Verificar saldo disponible en la cuenta origen con GET /accounts
EXC_017	400	Business	Se ha alcanzado el límite diario.	Esperar al siguiente día o contactar soporte para ampliar el límite
EXC_018	400	Business	Se ha alcanzado el límite de transacciones del plan.	Contactar soporte para ampliar el plan
EXC_019	400	Business	No se puede realizar el pago con la cuenta elegida.	Verificar que la cuenta origen esté activa y habilitada para dispersiones
EXC_032	409	Business	La llave de idempotencia ya fue procesada.	Usar una nueva idempotency-key. Cada llave expira en 24 horas

Errores de autenticación y autorización

Aplican a todos los endpoints BRE-B.

Código	HTTP	Mensaje	Acción recomendada
401	401	Unauthorized	Verificar que la x-api-key es correcta y está siendo enviada en los headers
403	403	Payer not found	Verificar que el user-principal-id corresponde a un payer registrado
403	403	Customer is employed and not allowed	El usuario no tiene permisos de dispersión. Contactar al administrador
403	403	Payer not have active product	El payer no tiene el producto de Pagos a Terceros activo. Activarlo desde el dashboard

Errores de validación de campos

Cuando se envían campos con formato incorrecto o faltantes, se retorna un error 400 con un array de mensajes:

{
  "status": 400,
  "meta": {
    "trace_id": "6fbfdee0-1ed8-11f0-acf5-eb60899d3e82"
  },
  "code": "400",
  "message": [
    "reference must be a string",
    "reference should not be empty"
  ],
  "data": {
    "message": [
      "reference must be a string",
      "reference should not be empty"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
}

Validaciones de idempotency-key

Mensaje	Causa
The key can only contain letters, numbers, and hyphens	La idempotency-key contiene caracteres especiales no permitidos

Validaciones del body

Mensaje	Causa
reference must be a string	Campo reference faltante o con tipo incorrecto
reference should not be empty	Campo reference vacío
accountId must be a string	Campo accountId faltante
paymentType must be one of: PAYROLL, PROVIDERS, OTHER	Valor de paymentType inválido
transactions must contain at least 1 element	Array de transacciones vacío
amount must be a positive number	Monto negativo o cero
email must be an email	Formato de email inválido
name should not be empty	Nombre del beneficiario vacío

Formatos de llave BRE-B

Referencia rápida para validar el formato antes de enviar la solicitud:

Tipo	Formato esperado	Ejemplo válido	Patrón
ALPHANUMERIC	@ + 5 a 20 caracteres alfanuméricos	@JUANPEREZ	^@[a-zA-Z0-9]{5,20}$
MAIL	Email válido	juan@email.com	RFC 5322
PHONE	10 dígitos, inicia con 3	3001234567	^3[0-9]{9}$
IDENTIFICATION	1 a 18 caracteres alfanuméricos	1234567890	^[a-zA-Z0-9]{1,18}$
ESTABLISHMENT_CODE	8 dígitos	12345678	^[0-9]{8}$

Buenas prácticas para manejo de errores

• Siempre capturar el trace_id: Al reportar un error a soporte, incluir el trace_id de la respuesta para facilitar la trazabilidad.
• Reintentos para errores técnicos: Los errores con type: "Technical" (EXC_001, EXC_036, EXC_037) pueden ser transitorios. Implementar reintentos con backoff exponencial.
• No reintentar errores de negocio: Los errores con type: "Business" (EXC_008, EXC_033, EXC_034) requieren corrección del request antes de reintentar.
• Validar localmente antes de enviar: Validar el formato de la llave BRE-B contra los patrones de la tabla antes de hacer la solicitud al API.