Errores y reintentos

La API Transaccional usa dos familias de respuesta para señalizar problemas: códigos HTTP (problemas de transporte, autenticación o rate limit) y validación de negocio (problemas semánticos del payload, devueltos como HTTP 200 con valid: false). Entender la diferencia es clave para reintentar sin generar transacciones duplicadas.

Códigos HTTP

CampoTipoDescripción

400

Bad Request

Payload con formato o tipos inválidos. Revisa los campos antes de reintentar.

401

Unauthorized

Token ausente, expirado o inválido. Refresca el access token y reintenta una vez.

403

Forbidden

IP fuera de la lista permitida, credencial en estado BLOCKED/REVOKED o política denegada. No reintentar hasta corregir la causa.

409

Conflict

Conflicto por externalReferenceId duplicado. Reintentar con el mismo ID es idempotente; reintentar con uno nuevo creará otra transacción.

429

Too Many Requests

Rate limit excedido. Aplica backoff exponencial y respeta el header Retry-After cuando esté presente.

5xx

Server Error

Error transitorio del procesador. Reintenta respetando el tiempo de espera y el mismo externalReferenceId.

Nunca uses 422

El conjunto de errores de la API Transaccional no incluye HTTP 422. Si ves ese código en una respuesta, llegó de un proxy o middleware intermedio. La API real devuelve 400 (payload inválido) o 200 con valid: false (validación de negocio).

Validación de negocio — 200 + valid: false

Cuando la petición está bien formada pero viola una regla de negocio (monto fuera de rango, cuenta inválida, propósito bloqueado, etc.) la API responde con HTTP 200 y un cuerpo con la lista de violaciones.

Campo	Descripción
valid	true cuando el payload pasa todas las validaciones; false en caso contrario.
status	PROCESSING cuando se acepta; FAILED cuando se rechaza por validación.
violations	Lista de violaciones. Vacía cuando valid: true.

Reintento seguro

Un 200 + valid: false no se reintenta de forma automática. La decisión depende de las reglas violadas: ajusta el payload con el Arma tu request, revisa el esquema en Esquemas y ejemplos y vuelve a ejecutar la transacción.

Reintentos idempotentes

El externalReferenceId es el identificador único de cada transacción del lado del cliente. Es la única garantía de idempotencia que ofrece la API.

Mismo externalReferenceId en reintentos

Si una petición a /b2b/transactions/payments terminó con timeout o error transitorio, reintenta con el mismo externalReferenceId. El procesador lo usará para deduplicar y evitar un cargo doble. Generar un ID nuevo en cada reintento crea transacciones duplicadas.

Reglas prácticas

• Timeouts / 5xx: reintenta con el mismo externalReferenceId usando backoff exponencial. Si el segundo intento también falla, espera un poco más antes del tercero.
• 409 Conflict: la transacción ya fue procesada. Verifica el estado usando el endpoint de consulta antes de decidir si reenviar.
• 429 Too Many Requests: respeta el header Retry-After si está presente. Si no, espera al menos 1 segundo y duplica el tiempo en cada reintento (1s → 2s → 4s → 8s, tope 30s).
• 401 Unauthorized: intenta una sola vez refrescar el token. Si persiste, el problema es de credenciales, no de transporte.
• 403 Forbidden: no reintentes. Resuelve la causa raíz primero.

Backoff sugerido

Intento	Espera mínima	Espera sugerida
1	—	primer intento fallido
2	500 ms	1 segundo
3	1 s	2 segundos
4	2 s	4 segundos
5	4 s	8 segundos
6+	8 s	16–30 segundos

Soporte

Si necesitas ayuda para investigar un estado inesperado o una petición fallida, escríbenos a soporte.tech@global66.com indicando el clientId y un ejemplo de la petición fallida (timestamp, request id, status HTTP).