Siete códigos, y sólo dos se reintentan

Un solo sobre para todos los errores

Cualquier respuesta que no sea un 2xx trae exactamente esta forma. Sin excepciones, sin páginas HTML de error y sin un formato distinto según el recurso.

{
  "error": {
    "codigo": "no_encontrado",
    "mensaje": "No existe una factura con ese identificador.",
    "detalles": null
  }
}

• codigo es para tu programa: es lo que puedes meter en un switch. Hoy son siete y un código existente no se renombra nunca, porque eso rompería el if de quien ya integra sin que nadie se entere. Lo que sí puede pasar algún día es que se añada uno; deja una rama por defecto y no te pillará.
• mensaje es para una persona. Está en español y puede cambiar de redacción sin previo aviso, así que no lo uses para decidir nada: nunca compares el texto de un mensaje.
• detalles es null casi siempre. Cuando no lo es, trae el desglose de qué campo falla y por qué —y, en un 500, una referencia corta que localiza ese fallo exacto en nuestro registro.

Los siete códigos, y qué hacer con cada uno

La columna que importa es la tercera. Un error del que no sabes si reintentar es un error que acaba en una tarea manual a las once de la noche.

Y una precisión antes de la tabla: el codigo y el estado HTTP no son lo mismo. Los códigos son siete; los estados, uno más, porque error_interno viaja tanto en un 500 como en el 503 del PDF.

Regla corta: los 4xx son cosa tuya y reintentarlos sin cambiar nada sólo gasta cuota; los 5xx y el 429 son los que se reintentan.

El 422, que es el único que te dice dónde mirar

Cuando la validación falla, detalles trae una lista en campos, y cada entrada dice qué campo falla y por qué. El nombre del campo lleva el índice dentro cuando el fallo está en una lista, así que señala la línea exacta de una factura de treinta:

{
  "error": {
    "codigo": "datos_invalidos",
    "mensaje": "Los datos no son validos: iva no es un campo de este recurso.",
    "detalles": {
      "campos": [
        { "campo": "iva", "motivo": "no es un campo de este recurso" },
        { "campo": "lineas[1].precio", "motivo": "es obligatorio" }
      ]
    }
  }
}

Fíjate en que es una lista y no un objeto de campo a mensaje: un mismo campo puede fallar por dos motivos, y con un objeto uno de los dos se perdería. Y el índice va entre corchetes —lineas[1]—, contando desde cero, así que la segunda línea es la del uno.

Enséñaselo a quien esté usando tu integración en vez de tragártelo. La mitad de los 422 son un dato mal escrito en el otro sistema, y quien puede arreglarlo es quien lo escribió, no tú.

Y el motivo más aburrido de todos: un nombre de campo que no existe. La API no ignora en silencio lo que no conoce, así que un iva donde iba tipo_iva, o un concepto donde iba descripcion, sale por aquí. Si un ejemplo copiado de cualquier parte te devuelve un 422, esto es lo primero que hay que mirar.

Paginación por cursor, no por número de página

Todas las listas se recorren igual, con tres parámetros:

{
  "datos": [
    { "id": "clx3k2p9y0001qz8h5e6f7g8h",
      "referencia": "F27-0042", "total": 435.60 },
    { "id": "clx3k2p9y0004qz8hq7r8s9t0",
      "referencia": "F27-0041", "total": 1210.00 }
  ],
  "total": 1284,
  "limite": 2,
  "siguiente": "https://erp.cairos.es/api/v1/facturas?limite=2&desde=cmVjaWVudGV8MTc2..."
}

siguiente es la URL entera de la página que sigue, con los filtros que llevabas ya puestos. No es el cursor suelto: se pide tal cual y no hay que recomponer nada ni acordarse de arrastrar el ?estado= que pusiste al principio. Y total es cuántos hay en total, para poder enseñar un progreso.

Viene a null cuando ya no queda nada, y ésa —y no que datos venga vacío— es la condición con la que se termina el bucle.

Para volcar un histórico entero usa orden=antiguo, que va sobre una fecha que ya no se mueve. orden=modificado existe para los disparadores por sondeo de Make, Zapier y n8n —pone arriba lo último que ha cambiado— y tiene un coste que conviene saber: el orden se mueve mientras paginas, así que sirve para mirar las últimas y no para recorrer el histórico.

// "siguiente" ya viene con los filtros y el cursor dentro:
// se sigue tal cual y no se recompone nada.
async function todas(recurso) {
  const salida = [];
  let url = BASE + recurso + "?limite=200&orden=antiguo";

  while (url) {
    const r = await fetch(url, {
      headers: { Authorization: "Bearer " + CLAVE },
    });
    if (!r.ok) throw new Error("Cairos respondio " + r.status);

    const pagina = await r.json();
    salida.push(...pagina.datos);
    url = pagina.siguiente;
  }

  return salida;
}

<?php
function todas($base, $clave, $recurso) {
    $salida = [];
    $url = $base . $recurso . "?limite=200&orden=antiguo";

    while ($url) {
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            "Authorization: Bearer " . $clave,
        ]);
        $pagina = json_decode(curl_exec($ch), true);
        curl_close($ch);

        $salida = array_merge($salida, $pagina["datos"]);
        // La URL de la siguiente pagina, o null al acabar.
        $url = $pagina["siguiente"];
    }

    return $salida;
}

# Primera página
curl "https://erp.cairos.es/api/v1/facturas?limite=200" \
  -H "Authorization: Bearer $CAIROS_CLAVE"

# La siguiente es literalmente el campo "siguiente" de la
# respuesta anterior: se pide tal cual, sin tocarla.
SIGUIENTE=$(curl -s "https://erp.cairos.es/api/v1/facturas?limite=200" \
  -H "Authorization: Bearer $CAIROS_CLAVE" | jq -r '.siguiente')

curl "$SIGUIENTE" -H "Authorization: Bearer $CAIROS_CLAVE"

El límite de peticiones: 120 por minuto y por clave

120 peticiones por minuto y por clave, en ventana deslizante. Al pasarlo vuelve un 429 demasiadas_peticiones con un Retry-After que dice cuántos segundos esperar.

Deslizante y no un contador que se pone a cero al dar la hora: con eso se podrían meter 120 a las 10:00:59 y otras 120 a las 10:01:00, que son 240 en un segundo y es justo el pico que se quiere evitar.

Da de sobra para lo que se hace de verdad —una sincronización nocturna gasta unas tres llamadas por pedido, así que son unos cuarenta pedidos por minuto—, y es lo bastante bajo para que una integración en bucle no deje sin respuesta al resto de clientes.

Y no hace falta llevar la cuenta tú: las tres cabeceras RateLimit-* van en todas las respuestas, no sólo en el rechazo.

Aun así, escribe el cliente para que no dependa de la cifra, que es como hay que escribirlo de todos modos:

• Reintenta el 429 con espera creciente. Un segundo, dos, cuatro, ocho, y ríndete a los cinco intentos.
• Añade un poco de azar a la espera. Si cinco procesos tuyos reintentan al mismo tiempo, vuelven a chocar todos a la vez. Un margen aleatorio los separa.
• No hagas un bucle apretado. Para volcar mil facturas, limite=200 y cinco llamadas es mejor que mil llamadas de una en una, y encima es más rápido.
• Escucha en vez de preguntar. Consultar cada minuto por si hay algo nuevo es lo que agota cualquier límite. Para eso están los webhooks.

async function conReintento(peticion, intentos = 5) {
  for (let i = 0; i < intentos; i++) {
    const r = await peticion();

    // Sólo estos dos se reintentan. Un 4xx reintentado
    // gasta cuota y falla exactamente igual.
    if (r.status !== 429 && r.status < 500) return r;

    const espera = Math.pow(2, i) * 1000 + Math.random() * 400;
    await new Promise((listo) => setTimeout(listo, espera));
  }
  throw new Error("Cairos no responde despues de varios intentos");
}

Y cuando el error es nuestro

Un 500 error_interno significa que se ha roto algo por nuestro lado. Tres cosas que conviene hacer, en este orden:

1. Reintenta con espera creciente y con llave de idempotencia. Muchos 500 son pasajeros.
2. Si insiste, para. Un proceso que reintenta indefinidamente contra un servidor caído no ayuda a nadie, y menos a que se levante antes.
3. Cuéntanoslo con la referencia. Un 500 trae en error.detalles.referencia una cadena corta —ocho caracteres— que es la que identifica ese fallo concreto en nuestro registro. Guárdala en tu propio log y pégala en el correo a info@cairos.es: con ella se encuentra en un minuto, y sin ella hay que ir adivinando por la hora.

Y lo que no hay que hacer: dar la operación por hecha o por no hecha. Un 500 no dice si el trabajo se hizo. Lo que lo dice es consultar el recurso, o haber mandado una llave de idempotencia y repetir la llamada.