The error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "receptor_incomplete",
    "message": "Receptor 76543212-K is missing `receptor.giro`, `receptor.address.street` and `receptor.address.comuna`, and tipo 33 cannot be filed without <GiroRecep>, <DirRecep>, <CmnaRecep>. Facturia looked: this empresa has emitted no earlier document to 76543212-K carrying them. …",
    "hint": "`error.param` names exactly which field to send. Facturia fills a receptor’s razón social, giro, dirección and comuna from this empresa’s own earlier documents to the same RUT; when there is no earlier one, they have to arrive with the request. Better here than an SII rejection with the folio already spent.",
    "retriable": false,
    "param": "receptor.giro",
    "doc_url": "https://docs.facturia.cl/errors/receptor_incomplete",
    "request_id": "req_01K2R7Q9M4T2VB",
    "empresa": "77928532-4"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "subscription_required",
    "message": "This live act needs an active subscription for this empresa, and it has none.",
    "retriable": false,
    "details": {
      "empresa": "emp_01K2R7Q4XW9M3B8ZC5YHTVJD6N",
      "empresa_rut": "77928532-4",
      "empresa_name": "Connect SpA",
      "account_plan": "starter",
      "subscription_status": "canceled",
      "grace_until": null,
      "checkout_url": "https://app.facturia.cl/…"
    }
  }
}

async function llamar(path, init) {
  const res = await fetch(`https://api.facturia.cl/v1${path}`, init);
  const requestId = res.headers.get('Facturia-Request-Id');

  if (res.ok) return { data: await res.json(), requestId };

  const { error } = await res.json();

  // `hint` viene en la respuesta: no hace falta ir a buscarlo al diccionario.
  // Falta solo si el código es más nuevo que tu cliente, así que hay fallback.
  log.warn({ requestId, code: error.code, quéHacer: error.hint ?? error.message });

  // El único caso en que el estado importa más que el tipo: falta pagar, y
  // `details.checkout_url` es lo que hay que ponerle delante a una persona.
  if (res.status === 402) {
    throw new PagoRequerido(error, error.details?.checkout_url, requestId);
  }

  // `retriable` responde «¿puede funcionar este MISMO request más rato?» para
  // cualquier código, incluidos los que salieron después de este switch.
  switch (error.type) {
    case 'rate_limit_error':
      // El header dice cuánto. No adivines.
      return { retryAfter: Number(res.headers.get('Retry-After') ?? 1), requestId };

    case 'api_error':
      // Nada se emitió. Reintenta con la MISMA Idempotency-Key.
      throw new Reintentable(error, requestId);

    case 'sii_error':
      // Puede ser transitorio. `error.sii` dice qué respondió el SII.
      throw new Reintentable(error, requestId);

    case 'invalid_request_error':
    case 'unprocessable_error':
      // Reintentar el mismo cuerpo va a fallar igual. Arréglalo o escálalo.
      throw new NoReintentable(error, requestId);

    default:
      // Un tipo que no reconoces: `retriable` sigue siendo una respuesta.
      throw error.retriable
        ? new Reintentable(error, requestId)
        : new NoReintentable(error, requestId);
  }
}

curl https://api.facturia.cl/v1/error_codes