Códigos HTTP y errores

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"
}

Ejemplos del resto de la documentación

En las páginas de endpoints se muestra solo el contenido de data, para no repetir el envoltorio en cada ejemplo. Sobre el cable siempre llega envuelto.

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

Probar tu manejo de errores

En sandbox puedes forzar cualquiera de estos errores con el campo simulate. Ver Modo Sandbox.

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

Pay-out con 502 o timeout

Un PROVIDER_ERROR o un timeout en una dispersión no significa que el dinero no salió. No crees otra transacción: reintenta con la misma X-Idempotency-Key o consulta el estado. Ver Idempotencia.

Errores de negocio de Nequi (422)

En los rechazos de negocio de Nequi, error.code es el código propio del proveedor y error.message ya viene traducido:

code	Mensaje
20-08A, 11-37L	El número de celular no tiene una cuenta Nequi.
20-05A	Datos de la solicitud inválidos.
20-10A	Servicio no habilitado para esta cuenta.
11-9L	No se pudo procesar la operación, intenta de nuevo.
11-36L	El monto supera el límite permitido para esta cuenta.
10-454	La transacción ya caducó.
2-CCSB000005	Esta cuenta Nequi no puede recibir plata en este momento.

Errores de Bre-B

HTTP	Forma
422	{ "error": "Bre-B rechazó la operación", "providerStatus": 400, "detail": "..." }
502	{ "error": "Bre-B no disponible" }
409	Onboarding incompleto — contacta con soporte

Saldo insuficiente

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

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

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.