Ir al contenido

Códigos HTTP y errores

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.

error.code es el valor estable para ramificar tu lógica; error.message es texto para humanos y puede cambiar.

error.codeHTTPSignificadoAcción recomendada
VALIDATION_ERROR400Body o parámetros inválidosRevisar el body del request
UNAUTHORIZED401Firma, timestamp, nonce o digest del body inválidosRegenerar timestamp + nonce + firma. Verificar que el body enviado sea exactamente el que se hasheó
INSUFFICIENT_FUNDS402Saldo insuficiente para la operaciónVerificar availableBalance en la respuesta
FORBIDDEN403Servicio no habilitado / producción no habilitadaContactar a Rivopay para activar el servicio
NOT_FOUND404Recurso o ruta inexistenteVerificar el txId o externalId
CONFLICT409Estado conflictivo (duplicado, onboarding incompleto)Verificar el estado actual de la transacción
IDEMPOTENCY_KEY_REQUIRED400Falta X-Idempotency-Key en una operación que mueve dineroEnviar la cabecera. Ver Idempotencia
IDEMPOTENCY_KEY_INVALID400X-Idempotency-Key con más de 128 caracteres o fuera de [A-Za-z0-9_-:.]Corregir el formato de la clave
IDEMPOTENCY_KEY_REUSED422X-Idempotency-Key ya usada con un cuerpo distintoUsar una clave nueva o enviar el mismo cuerpo original
IDEMPOTENCY_IN_FLIGHT409Otra petición con esa clave está en cursoReintentar en unos segundos
IDEMPOTENCY_CONFLICT409X-Idempotency-Key ya usada y sin transacción que devolverVer Idempotencia
QR_REFERENCE_CONFLICT409qrCodeReference ya utilizada en otro cobroEnviar otra referencia, o dejar que el gateway la genere
NEQUI_COMMERCE_NOT_CONFIGURED409Onboarding incompletoContacta con soporte
PROVIDER_REJECTED422El proveedor rechazó la operación (motivo de negocio)Revisar los datos enviados y el code del proveedor
IDENTIFICATION_MISMATCH422El documento enviado no es el del titular de la llave Bre-BConfirmar el documento del destinatario
RATE_LIMITED429Demasiadas peticionesReintentar con backoff
INTERNAL_ERROR500Error internoReintentar con backoff. Si persiste, contactar soporte
NOT_IMPLEMENTED501Operación no implementadaNo reintentar
PROVIDER_ERROR502Proveedor caído o con fallo transitorioReintentar en ~30 segundos
SERVICE_UNAVAILABLE503Servicio suspendido para tu cuentaContactar 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 (GET de la transacción, o reintento con la misma X-Idempotency-Key) hasta ver un estado final, o escríbenos a soporte con el externalId. 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).

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.

codeMensaje que llegaCuándoEstado de la tx
20-08A, 11-37LEl número de celular no tiene una cuenta Nequi.Cobro o dispersiónFallida (FAILED)
20-05ADatos de la solicitud inválidos.Cobro o dispersión (incluye referencia de dispersión repetida)Fallida (FAILED)
20-10AServicio no habilitado para esta cuenta.Cobro o dispersiónFallida (FAILED)
11-9LNo se pudo procesar la operación, intenta de nuevo.Cobro o dispersiónFallida (FAILED)
11-36LEl monto supera el límite permitido para esta cuenta.Cobro o dispersiónFallida (FAILED)
11-49L¡Uy! Tenemos un problema, los datos que ingresaste no están bien.CobroFallida (FAILED)
20-07A¡Error técnico!CobroFallida (FAILED)
2-CCSB000005¡Ups! Esta cuenta Nequi no puede recibir plata en este momento.DispersiónFallida (FAILED)
BUS001Cliente no activo o número de teléfono inválidoDispersiónFallida (FAILED)
ERR003El servicio actualmente no puede procesar la solicitudDispersiónFallida (FAILED)
ERR005El servicio se encuentra en mantenimiento, no podemos procesar tu solicitud en estos momentosDispersiónFallida (FAILED)
BP12900077Saldo insuficienteDispersiónFallida (FAILED)
43-DEP0049No tienes saldo suficiente en tu cuenta Bancolombia.DispersiónFallida (FAILED)
ERR004Error técnico internoDispersiónFallida (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.

codeMensaje de NequiEstado de la tx
10-454La transacción ya caducó.Vencida (EXPIRED)
10-455La 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-458Errores 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.
HTTPerror.codeerror.messageEstado de la tx
422PROVIDER_REJECTEDBre-B rechazó la operaciónFallida (FAILED), o sin tx si falló al validar la llave
404NOT_FOUNDLlave Bre-B no encontrada o no activaSin tx
502PROVIDER_ERRORBre-B no disponibleFallida (FAILED)
409CONFLICTOnboarding incompleto: contacta con soporteSin 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.detailSignificadoEstado de la tx
Key (TIPO:valor) not found in the central directory (DICE).La llave no existe en el directorio Bre-BFallida (FAILED)
Key operation rejected: DICE is unavailable. (U997)Directorio de llaves no disponible: reintenta más tardeFallida (FAILED)
Key operation rejected: Internal error: … (U500)Error interno de Bre-B: reintenta más tardeFallida (FAILED)
1 validation error for GetKeyResponse …Error interno de Bre-B: reintenta más tardeFallida (FAILED)
qr_code not found.El QR no existeFallida (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:

failureReasonCódigo de redSignificadoEstado de la tx
Payment rejected by entity / Payment rejected by the MOL with code B106B106La entidad del destinatario rechazó el pagoFallida (FAILED)
Bank validation errorB101 / B002La entidad del destinatario no validó la cuentaFallida (FAILED)
Bank validation timed outB101 / B002La entidad del destinatario no respondió a tiempoFallida (FAILED)
Timeout declared by the receptor node.B002El nodo receptor no respondió a tiempoFallida (FAILED)
Account specified is blocked, prohibiting posting of transactions against it.B101Cuenta del destinatario bloqueadaFallida (FAILED)
Dynamic QR code already usedB113El QR dinámico ya fue usadoFallida (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.

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 frecuenteQué revisarEstado de la tx
CPF/CNPJ con dígitos verificadores inválidosDocumento del pagador o del destinatarioFallida (FAILED)
Llave Pix inexistenteQue la llave esté registrada en el banco del destinatarioFallida (FAILED)
Llave Pix bloqueada por sospecha de fraudePedir otra llave al destinatarioFallida (FAILED)
Llave de correo con dominio inválidoEl correo usado como llaveFallida (FAILED)
Destinatario CNPJ (persona jurídica) no permitidoPagos a CNPJ no habilitados para tu cuenta: contacta con soporteFallida (FAILED)
Límite de consultas de llaves o consulta bloqueada temporalmenteReintenta en unos minutosFallida (FAILED)
Operación no permitida por el bancoReintenta más tarde o con otra llaveFallida (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.

El 402 incluye el detalle para que puedas mostrarlo o decidir el reintento:

{
"availableBalance": 30000,
"requiredAmount": 52000,
"currency": "COP"
}

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.