Errores y reintentos

Qué hace el SDK por ti y qué te toca decidir a ti.

​

Errores

Todo error de la API llega como DocondaError:

import { DocondaError } from "@doconda/sdk"

try {
  await doconda.documents.create({ format: "docx", prompt: "Memo para el equipo" })
} catch (e) {
  if (!(e instanceof DocondaError)) throw e
  console.log(e.status)    // 402
  console.log(e.code)      // "insufficient_balance": estable, úsalo para decidir
  console.log(e.message)   // explicación en inglés, para tus logs
  console.log(e.errors)    // en 422: qué campo está mal y por qué
  console.log(e.requestId) // dánoslo si escribes a soporte
}

Los que más vas a ver:

code	Qué hacer
input_invalid	Corrige la petición: e.errors dice qué campo.
insufficient_balance	Recarga saldo en el panel (o activa la recarga automática).
unauthorized	La key no existe o está revocada.
region_mismatch	La key es de otra región: no cambies baseUrl, el SDK ya elige la suya.
not_found	Ese documento no es de este proyecto.

La lista completa está en errores.

Un documento que falla al procesarse no es una excepción: create lo devuelve con status: "failed" y doc.error. No se cobra.

​

Reintentos

El SDK reintenta solo los fallos de red, 429 y 5xx, esperando cada vez un poco más (o lo que diga la API). Los errores de tu petición (4xx) no se reintentan: repetirlos daría lo mismo.

​

Nunca dos veces el mismo documento

Cada creación lleva una Idempotency-Key: si un reintento llega después de que el primero sí funcionara, la API devuelve el mismo documento en vez de crear (y cobrar) otro.

Si tu programa puede repetir la operación por su cuenta (un job que se reintenta, un usuario que pulsa dos veces), pasa tu propia clave, estable para esa operación:

await doconda.documents.create({ format: "docx", prompt: "…" }, { idempotencyKey: `carta-bienvenida-${userId}` })

La API la recuerda 24 horas.