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 una lista cerrada de siete valores y no va a crecer sin avisar: es lo que puedes meter en un switch.
• 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é.

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.

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

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

Cuando la validación falla, detalles trae un objeto con el camino del campo y el motivo. El camino usa puntos e índices, así que señala también dentro de una lista de líneas:

{
  "error": {
    "codigo": "datos_invalidos",
    "mensaje": "La factura tiene dos campos que no son válidos.",
    "detalles": {
      "contacto_id": "No existe ningún contacto con ese identificador.",
      "lineas.0.iva": "Tipo de IVA no permitido: 19."
    }
  }
}

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ú.

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

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

{
  "datos": [
    { "id": "fac_5Np2wD", "numero": "F27/0042", "total": 435.60 },
    { "id": "fac_4Mq1vC", "numero": "F27/0041", "total": 1210.00 }
  ],
  "total": 1284,
  "siguiente": "fac_4Mq1vC"
}

total es cuántos hay en total, para poder enseñar un progreso. siguiente 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.

async function todas(recurso) {
  const salida = [];
  let desde = null;

  do {
    const url = new URL(BASE + recurso);
    url.searchParams.set("limite", "200");
    if (desde) url.searchParams.set("desde", desde);

    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);
    desde = pagina.siguiente;
  } while (desde);

  return salida;
}

<?php
function todas($base, $clave, $recurso) {
    $salida = [];
    $desde  = null;

    do {
        $url = $base . $recurso . "?limite=200";
        if ($desde) {
            $url .= "&desde=" . urlencode($desde);
        }

        $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"]);
        $desde  = $pagina["siguiente"];
    } while ($desde);

    return $salida;
}

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

# Siguiente, con el cursor de la anterior
curl "https://erp.cairos.es/api/v1/facturas?limite=200&desde=fac_4Mq1vC" \
  -H "Authorization: Bearer $CAIROS_CLAVE"

Límites: lo que hay y lo que no vamos a inventar

Hay un límite de peticiones por clave, y al pasarlo vuelve un 429 demasiadas_peticiones. Eso es firme.

La cifra exacta no está publicada todavía, y no la vamos a poner aquí a ojo. Es el único dato de toda esta sección que no puedes comprobar tú mismo hasta que te explota en producción, así que un número inventado sería peor que ninguno. Cuando esté fijada, se escribe aquí.

Lo que sí se puede decir es cómo se escribe un cliente que no depende de esa 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. A hola@cairos.es, con la hora aproximada y qué llamabas. Con eso se encuentra en el registro; sin eso, casi nunca.

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.