Códigos HTTP y errores
Formato de respuestas (envelope v2)
Sección titulada «Formato de respuestas (envelope v2)»Todas las respuestas JSON de la API firmada viajan envueltas. No leas los campos de negocio en la raíz: están dentro de data.
Éxito:
{ "success": true, "data": { "txId": "a1b2c3…", "status": "PENDING" }, "requestId": "abc123-def456"}Error:
{ "success": false, "error": { "code": "VALIDATION_ERROR", "message": "amount requerido (pesos COP enteros > 0)", "details": { "campo": "valor" } }, "requestId": "abc123-def456"}requestId es el identificador que asigna API Gateway a la petición. Guárdalo: es lo que permite correlacionar tu llamada con nuestros logs al reportar un problema.
Códigos de error
Sección titulada «Códigos de error»error.code es el valor estable para ramificar tu lógica; error.message es texto para humanos y puede cambiar.
error.code | HTTP | Significado | Acción recomendada |
|---|---|---|---|
VALIDATION_ERROR | 400 | Body o parámetros inválidos | Revisar el body del request |
UNAUTHORIZED | 401 | Firma, timestamp, nonce o digest del body inválidos | Regenerar timestamp + nonce + firma. Verificar que el body enviado sea exactamente el que se hasheó |
INSUFFICIENT_FUNDS | 402 | Saldo insuficiente para la operación | Verificar availableBalance en la respuesta |
FORBIDDEN | 403 | Servicio no habilitado / producción no habilitada | Contactar a Rivopay para activar el servicio |
NOT_FOUND | 404 | Recurso o ruta inexistente | Verificar el txId o externalId |
CONFLICT | 409 | Estado conflictivo (duplicado, onboarding incompleto) | Verificar el estado actual de la transacción |
IDEMPOTENCY_KEY_REQUIRED | 400 | Falta X-Idempotency-Key en una operación que mueve dinero | Enviar la cabecera. Ver Idempotencia |
IDEMPOTENCY_KEY_INVALID | 400 | X-Idempotency-Key con más de 128 caracteres o fuera de [A-Za-z0-9_-:.] | Corregir el formato de la clave |
IDEMPOTENCY_KEY_REUSED | 422 | X-Idempotency-Key ya usada con un cuerpo distinto | Usar una clave nueva o enviar el mismo cuerpo original |
IDEMPOTENCY_IN_FLIGHT | 409 | Otra petición con esa clave está en curso | Reintentar en unos segundos |
IDEMPOTENCY_CONFLICT | 409 | X-Idempotency-Key ya usada y sin transacción que devolver | Ver Idempotencia |
QR_REFERENCE_CONFLICT | 409 | qrCodeReference ya utilizada en otro cobro | Enviar otra referencia, o dejar que el gateway la genere |
NEQUI_COMMERCE_NOT_CONFIGURED | 409 | Onboarding incompleto | Contacta con soporte |
PROVIDER_REJECTED | 422 | El proveedor rechazó la operación (motivo de negocio) | Revisar los datos enviados y el code del proveedor |
IDENTIFICATION_MISMATCH | 422 | El documento enviado no es el del titular de la llave Bre-B | Confirmar el documento del destinatario |
RATE_LIMITED | 429 | Demasiadas peticiones | Reintentar con backoff |
INTERNAL_ERROR | 500 | Error interno | Reintentar con backoff. Si persiste, contactar soporte |
NOT_IMPLEMENTED | 501 | Operación no implementada | No reintentar |
PROVIDER_ERROR | 502 | Proveedor caído o con fallo transitorio | Reintentar en ~30 segundos |
SERVICE_UNAVAILABLE | 503 | Servicio suspendido para tu cuenta | Contactar soporte |
Errores de proveedor y estado de la transacción
Sección titulada «Errores de proveedor y estado de la transacción»La columna Estado de la tx dice en qué queda la transacción con cada error:
- Fallida (
FAILED) o Vencida (EXPIRED): desenlace definitivo. No salió dinero y el saldo retenido se liberó, así que puedes declinar en tu sistema. - Sin tx: el error llegó antes de crear la operación. No hay nada que consultar.
- Incierta (
PENDING): el proveedor no confirmó si la operación se ejecutó. No la declines ni crees otra. Consulta el estado (GETde la transacción, o reintento con la mismaX-Idempotency-Key) hasta ver un estado final, o escríbenos a soporte con elexternalId. El saldo queda retenido mientras tanto.
En Nequi y Pix, un 502 PROVIDER_ERROR o un timeout sin respuesta es Incierta. En Bre-B, el 502 queda Fallida (FAILED).
Errores de Nequi (422)
Sección titulada «Errores de Nequi (422)»En los rechazos de Nequi, error.code es el código propio del proveedor. error.message viene traducido cuando el código tiene mensaje propio; si no, llega el texto original de Nequi.
code | Mensaje que llega | Cuándo | Estado de la tx |
|---|---|---|---|
20-08A, 11-37L | El número de celular no tiene una cuenta Nequi. | Cobro o dispersión | Fallida (FAILED) |
20-05A | Datos de la solicitud inválidos. | Cobro o dispersión (incluye referencia de dispersión repetida) | Fallida (FAILED) |
20-10A | Servicio no habilitado para esta cuenta. | Cobro o dispersión | Fallida (FAILED) |
11-9L | No se pudo procesar la operación, intenta de nuevo. | Cobro o dispersión | Fallida (FAILED) |
11-36L | El monto supera el límite permitido para esta cuenta. | Cobro o dispersión | Fallida (FAILED) |
11-49L | ¡Uy! Tenemos un problema, los datos que ingresaste no están bien. | Cobro | Fallida (FAILED) |
20-07A | ¡Error técnico! | Cobro | Fallida (FAILED) |
2-CCSB000005 | ¡Ups! Esta cuenta Nequi no puede recibir plata en este momento. | Dispersión | Fallida (FAILED) |
BUS001 | Cliente no activo o número de teléfono inválido | Dispersión | Fallida (FAILED) |
ERR003 | El servicio actualmente no puede procesar la solicitud | Dispersión | Fallida (FAILED) |
ERR005 | El servicio se encuentra en mantenimiento, no podemos procesar tu solicitud en estos momentos | Dispersión | Fallida (FAILED) |
BP12900077 | Saldo insuficiente | Dispersión | Fallida (FAILED) |
43-DEP0049 | No tienes saldo suficiente en tu cuenta Bancolombia. | Dispersión | Fallida (FAILED) |
ERR004 | Error técnico interno | Dispersión | Fallida (FAILED) |
ERR003, ERR004, ERR005, BP12900077, 43-DEP0049, 11-9L y 20-07A son indisponibilidad temporal de Nequi, no un problema con tus datos: puedes reintentar más tarde.
Códigos de la consulta de estado de un cobro. Estos no llegan como respuesta a tu petición: los ves en el desenlace del cobro, por webhook y en la consulta de la transacción.
code | Mensaje de Nequi | Estado de la tx |
|---|---|---|
10-454 | La transacción ya caducó. | Vencida (EXPIRED) |
10-455 | La transacción esta cancelada (el usuario la rechazó o se canceló el push) | Fallida (FAILED) |
11-9L, 11-18L, 11-20L, 20-05A, 20-07A, 3-458 | Errores técnicos repetidos (“¡No pudimos hacer esto!”, “¡Error técnico!”, “Algo falló…”) | Sigue PENDING hasta 45 min de vida y luego Vencida (EXPIRED). Si el pago llega después, se cierra COMPLETED. |
Errores de Bre-B
Sección titulada «Errores de Bre-B»| HTTP | error.code | error.message | Estado de la tx |
|---|---|---|---|
422 | PROVIDER_REJECTED | Bre-B rechazó la operación | Fallida (FAILED), o sin tx si falló al validar la llave |
404 | NOT_FOUND | Llave Bre-B no encontrada o no activa | Sin tx |
502 | PROVIDER_ERROR | Bre-B no disponible | Fallida (FAILED) |
409 | CONFLICT | Onboarding incompleto: contacta con soporte | Sin tx |
En los cobros (QR y llave), el 422 trae el motivo original de Bre-B en error.details.detail. Los más frecuentes:
details.detail | Significado | Estado de la tx |
|---|---|---|
Key (TIPO:valor) not found in the central directory (DICE). | La llave no existe en el directorio Bre-B | Fallida (FAILED) |
Key operation rejected: DICE is unavailable. (U997) | Directorio de llaves no disponible: reintenta más tarde | Fallida (FAILED) |
Key operation rejected: Internal error: … (U500) | Error interno de Bre-B: reintenta más tarde | Fallida (FAILED) |
1 validation error for GetKeyResponse … | Error interno de Bre-B: reintenta más tarde | Fallida (FAILED) |
qr_code not found. | El QR no existe | Fallida (FAILED) |
En los pagos (payout), el 422 trae details.providerStatus (400, 404) y el motivo original de Bre-B en details.detail, igual que en los cobros (por ejemplo Unexpected field 'owner.name'). Una llave inexistente se detecta antes de crear el pago y responde 404 sin crear transacción. Si validate-key responde 422 con providerStatus: 400, revisa que no envíes campos que Bre-B no admite dentro de owner (por ejemplo owner.name).
Rechazos de la red en un pago. El failureReason del webhook y de la consulta llega con la descripción original de Bre-B:
failureReason | Código de red | Significado | Estado de la tx |
|---|---|---|---|
Payment rejected by entity / Payment rejected by the MOL with code B106 | B106 | La entidad del destinatario rechazó el pago | Fallida (FAILED) |
Bank validation error | B101 / B002 | La entidad del destinatario no validó la cuenta | Fallida (FAILED) |
Bank validation timed out | B101 / B002 | La entidad del destinatario no respondió a tiempo | Fallida (FAILED) |
Timeout declared by the receptor node. | B002 | El nodo receptor no respondió a tiempo | Fallida (FAILED) |
Account specified is blocked, prohibiting posting of transactions against it. | B101 | Cuenta del destinatario bloqueada | Fallida (FAILED) |
Dynamic QR code already used | B113 | El QR dinámico ya fue usado | Fallida (FAILED) |
En un cobro (QR o llave), un intento rechazado por la red no cierra la transacción: sigue PENDING y el pagador puede volver a intentarlo hasta que venza.
Errores de Pix (Brasil)
Sección titulada «Errores de Pix (Brasil)»Los rechazos de Pix llegan como 422 PROVIDER_REJECTED con el mensaje genérico "Payment provider rejected the request". Siempre son definitivos: la transacción queda Fallida (FAILED) y no salió dinero.
| Causa frecuente | Qué revisar | Estado de la tx |
|---|---|---|
| CPF/CNPJ con dígitos verificadores inválidos | Documento del pagador o del destinatario | Fallida (FAILED) |
| Llave Pix inexistente | Que la llave esté registrada en el banco del destinatario | Fallida (FAILED) |
| Llave Pix bloqueada por sospecha de fraude | Pedir otra llave al destinatario | Fallida (FAILED) |
| Llave de correo con dominio inválido | El correo usado como llave | Fallida (FAILED) |
| Destinatario CNPJ (persona jurídica) no permitido | Pagos a CNPJ no habilitados para tu cuenta: contacta con soporte | Fallida (FAILED) |
| Límite de consultas de llaves o consulta bloqueada temporalmente | Reintenta en unos minutos | Fallida (FAILED) |
| Operación no permitida por el banco | Reintenta más tarde o con otra llave | Fallida (FAILED) |
Si un pago Pix no se confirma a tiempo, la creación responde 202 Accepted con status: PENDING: es Incierta y el desenlace llega por webhook.
Saldo insuficiente
Sección titulada «Saldo insuficiente»El 402 incluye el detalle para que puedas mostrarlo o decidir el reintento:
{ "availableBalance": 30000, "requiredAmount": 52000, "currency": "COP"}Soporte
Sección titulada «Soporte»Al reportar un problema incluye siempre el requestId de la respuesta (o el txId / externalId): es lo que permite localizar la operación en los logs.