Errores

Toda integración seria se define por cómo maneja lo que sale mal, no por el camino feliz. En esta página te explicamos, sin dar nada por sabido, cómo Alibanca te reporta un error: la forma exacta del cuerpo de respuesta, qué significa cada código HTTP, y —lo más importante para no perder ni duplicar dinero— cuándo debes reintentar una operación y cuándo NO. Léela completa antes de mandar tu primer pago de verdad: aquí es donde la idempotencia y el estado unknown dejan de ser teoría y se vuelven decisiones de código.

La forma de un error

Cuando una petición sale bien, Alibanca te responde con un cuerpo JSON que siempre tiene la misma estructura: un status en "success", un traceId (un identificador único de esa petición, útil para soporte) y un payload con los datos que pediste. Un error es lo contrario y es igual de predecible: un único campo error con un mensaje legible, acompañado de un código de estado HTTP distinto de 2xx. Nada más. No hay diez formatos de error escondidos; hay uno solo.

{
  "error": "amountMinor es obligatorio"
}

Dos piezas, entonces, y las dos importan:

Un error HTTP NO es un pago fallido

Esta es, de lejos, la confusión que más caro cuesta, así que la aclaramos de una vez. Hay dos mundos distintos y no se tocan:

Mundo 1 — el resultado de la petición HTTP. ¿Alibanca aceptó y procesó tu llamada? Eso lo responde el código HTTP. Un 4xx/5xx significa que la petición como tal no prosperó (o no sabemos si prosperó).

Mundo 2 — el estado del dinero. Cuando emites un pago y la petición SÍ prospera, recibes un 201 con un payload que trae el campo state. Ese state vive dentro de una respuesta exitosa:

Fíjate en la trampa: un pago con state: "failed" te llega dentro de un 201, no de un HTTP 4xx. Que el pago haya fallado no quiere decir que tu request haya fallado — tu request fue perfecto, Alibanca lo aceptó, lo intentó, y el banco lo rechazó. Por eso el estado del pago viaja en el payload de una respuesta de éxito, y no como un error HTTP.

El mapa de códigos HTTP

Alibanca usa códigos HTTP estándar, sin sorpresas. Los agrupamos en familias por el primer dígito: los 4xx significan "el problema está en tu petición, corrígela"; los 5xx significan "el problema está de nuestro lado". Esta tabla es tu referencia rápida; abajo desarrollamos cada familia con ejemplos.

400 — el request está mal formado

Un 400 es un error de validación: Alibanca miró tu petición antes de tocar dinero y encontró que no cumple el contrato. Es el error más común mientras desarrollas, y también el más fácil de arreglar, porque el mensaje te dice exactamente qué campo revisar. Nada de dinero se movió: un 400 se rechaza en la puerta.

Las causas típicas de un 400 en POST /v2/payments:

// Enviaste beneficiaryId y también rail+beneficiary a la vez
{
  "error": "El destino debe ser beneficiaryId O (rail + beneficiary), no ambos"
}

Cómo reaccionar a un 400: no reintentes con la misma petición — vas a recibir el mismo 400 para siempre. Un 400 es determinístico: mismo request, mismo rechazo. Corrige el campo que el mensaje señala y vuelve a enviar. Como no se creó ningún pago, puedes reusar la misma idempotency-key sin peligro cuando reenvíes ya corregido.

401 — autenticación o firma inválida

El 401 dice: "no pude confirmar que eres tú". Como cada petición a Alibanca va autenticada por partida doble —con tu x-api-key y con una firma x-signature RSA-SHA256 sobre un envelope canónico— un 401 puede venir de varios puntos de esa cadena. Repasemos los sospechosos habituales:

{
  "error": "firma inválida"
}

Cómo reaccionar a un 401: nunca reintentes con exactamente los mismos headers — el resultado no va a cambiar. Un 401 casi siempre es un bug de tu firma o de tus credenciales, no un fallo transitorio. Detén la operación, registra el error, y revisa cómo estás construyendo el envelope. El único "reintento" válido es después de corregir la firma o la llave — y ahí el nonce debe ser uno nuevo y mayor.

404 — el recurso no existe

Un 404 significa que apuntaste a algo que Alibanca no encuentra. Dos variantes: (1) la ruta está mal escrita —por ejemplo /v2/payment/… en singular cuando es /v2/payments/…—, o (2) el identificador no corresponde a ningún recurso tuyo: un paymentId que no existe, un beneficiaryId que archivaste o que nunca creaste, o el id de otra cuenta que no es la de tu llave.

// GET /v2/payments/pay_no_existe
{
  "error": "pago no encontrado"
}

Cómo reaccionar a un 404: reintentar no va a crear el recurso, así que no reintentes en bucle. Verifica primero que el id sea el correcto y que pertenezca a tu llave. Hay un matiz útil, eso sí: si acabas de crear algo y lo consultas inmediatamente, un 404 momentáneo puede ser una carrera de lectura muy corta; en ese caso, un único reintento con un pequeño respiro es razonable. Pero un 404 persistente = el recurso no está, punto.

409 — conflicto de idempotencia o unicidad

El 409 es el más interesante y el que más gente malinterpreta, porque no siempre es "algo salió mal" — a veces es "ya hiciste esto, aquí no hay nada nuevo que crear". Recuerda qué es la idempotency-key: un identificador único y determinístico que tú generas por cada operación lógica. Su propósito es que reintentar una operación devuelva el mismo resultado en vez de crear un pago duplicado. El 409 aparece cuando esa promesa entra en tensión:

{
  "error": "idempotency-key ya usada con un cuerpo distinto"
}

Cómo reaccionar a un 409: nunca lo trates como "reintento fallido, dale otra vez". Un 409 te está diciendo que hay estado del lado de Alibanca que no debes pisar. Si el conflicto es de idempotencia con cuerpo distinto, revisa tu generación de keys — probablemente estás reusando una key por accidente. Si de verdad querías consultar el resultado de esa operación previa, haz un GET /v2/payments/:id y lee su estado.

422 y otras reglas de negocio

Un 422 (u otro código de la familia 4xx que uses para dominio) significa que tu petición estaba sintácticamente perfecta —todos los campos presentes y bien tipados— pero viola una regla del negocio. La diferencia con el 400 es importante: el 400 es "no entiendo tu request"; el 422 es "entiendo tu request perfectamente, pero no puedo cumplirlo". Casos típicos: saldo insuficiente para el monto que pides, o un monto que supera un límite de tu llave (los limits que ves en GET /v2/me, que combinan tus propios topes con los pisos que impone Alibanca).

{
  "error": "saldo insuficiente para el monto solicitado"
}

Cómo reaccionar: reintentar la misma operación idéntica dará el mismo rechazo, porque la regla no cambió por reintentar. Lo que corresponde es ajustar la operación (bajar el monto, fondear saldo, respetar el límite) y luego enviar. Como no se creó ningún pago, puedes usar una idempotency-key nueva para el intento corregido.

5xx — el problema es nuestro (y aquí sí reintentas)

Los 5xx son la única familia donde tu código sí debe reintentar automáticamente, porque el fallo no está en tu petición sino de nuestro lado: un error interno (500) o un componente temporalmente indisponible. La web se cae a ratos; una buena integración lo absorbe. Pero hay una regla no negociable, y es donde la idempotencia se vuelve tu salvavidas.

Este es el patrón de reintento seguro para un 5xx o un timeout, con espera exponencial ("backoff": esperas cada vez un poco más entre intentos para no golpear un servicio que se está recuperando):

const idem = "pago-orden-8842";  // misma key en TODOS los intentos
const body = JSON.stringify({ amountMinor: "150000", currency: "VES", beneficiaryId: "ben_123" });

for (let intento = 0; intento < 5; intento++) {
  const res = await enviarPago({ idem, body });  // mismo idem, mismo body

  if (res.status < 500) return res;       // 2xx/4xx: resuelto, no reintentar

  await esperar(2 ** intento * 200);          // backoff: 200ms, 400ms, 800ms…
}

Cómo reaccionar a un 5xx, resumido: reintenta —pero con la misma key, el mismo cuerpo, un backoff creciente y un tope de intentos—. Si tras varios intentos sigues recibiendo 5xx, deja de martillar y pasa a verificar por otro camino: consulta el estado con GET /v2/payments/:id (usando el id si lo tienes) o revisa tu GET /v2/balance. Y recuerda que, aun cuando la petición eventualmente prospere, el pago resultante puede quedar en unknown — que es otra cosa y se resuelve por conciliación, no por reintento.

El árbol de decisión: ¿reintento o no?

Junta todo lo anterior en una sola regla mental. Cuando recibas una respuesta que no es 2xx, pregúntate esto en orden:

Pruébalo en sandbox

La mejor forma de blindar tu manejo de errores es provocarlos a propósito en el sandbox, donde el proveedor es simulado y no se mueve un centavo real. Genera un 400 mandando un pago sin amountMinor. Genera un 401 firmando con un nonce repetido. Genera un 409 reusando una idempotency-key con un cuerpo distinto. Y para el flujo unknown, usa los montos mágicos.

Buenas prácticas de manejo de errores

Cerramos con la lista corta que separa una integración de juguete de una de producción:

Con esto tienes el cuadro completo: una sola forma de error ({ "error": "…" } + código HTTP), un árbol de decisión claro por familia de código, y la coordinación entre la idempotencia y el estado unknown que mantiene tu dinero —y el de tus usuarios— a salvo de duplicados. Cuando termines de integrar el camino feliz, vuelve a esta página y asegúrate de que cada rama de error tenga su manejo. Ahí es donde se gana la confianza.