Errores y límites

Qué significa cada respuesta y cuál de ellas conviene reintentar.

Forma de un error

Un error llega con el mismo sobre que una respuesta correcta, pero con error en vez de data:

json

{
  "status": 400,
  "error": "Validation error",
  "errors": [
    { "path": ["amount"], "message": "Expected number, received string" }
  ]
}

En los errores de validación, errors nombra el campo y qué se esperaba. Es la forma más rápida de conocer el contrato de un endpoint: manda una petición incompleta a propósito y lee lo que responde.

Códigos

Código	Qué pasó	¿Reintentar?
`400`	Los datos que mandaste no pasan la validación. El cuerpo dice qué campo.	No. Reintentar lo mismo da lo mismo.
`401`	Falta la clave, o está revocada, caducada o no existe.	No hasta revisar la clave.
`403`	La clave es válida pero el usuario que la creó no tiene ese permiso.	No. Hay que conceder el permiso.
`404`	El recurso no existe — o es de otra empresa, que desde fuera es lo mismo.	No.
`429`	Superaste el límite de peticiones de la clave.	Sí, esperando. Ver abajo.
`500`	Fallo del lado de la plataforma.	Sí, con espera creciente.

Límite de peticiones

Cada clave tiene su propio límite, configurable, con un valor por defecto de 60 peticiones por minuto. Al superarlo la respuesta es 429.

El límite es por clave, no por empresa: si tienes varios sistemas integrados, dale una clave a cada uno. Además de repartir el límite, eso permite revocar el que se porte mal sin dejar fuera a los demás.

Cómo reintentar

Con espera creciente, no en bucle cerrado. Un reintento inmediato contra un 429 solo consume el límite del siguiente minuto y alarga el bloqueo.

javascript

async function conReintentos(peticion, intentos = 4) {
  for (let i = 0; i < intentos; i++) {
    const res = await peticion();

    // 429 y 5xx son transitorios; el resto no se arregla repitiendo.
    if (res.status !== 429 && res.status < 500) return res;

    // 1s, 2s, 4s, 8s.
    await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
  }
  throw new Error("La plataforma no respondió tras varios intentos");
}

Reintentar una ingesta es seguro

La ingesta de transacciones es idempotente por empresa y referencia: reenviar la misma transacción no la duplica. Por eso puedes reintentar un lote entero sin comprobar antes cuáles llegaron.

Tiempos de espera

Pon un tiempo límite en tu cliente —30 segundos es razonable— y trátalo como un error transitorio. Sin él, una petición colgada bloquea tu proceso indefinidamente, que es peor que un fallo rápido.