For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/developers/error-handling.md.
Kivox

Manejo de errores

El formato y la estructura de un error y el catálogo completo de códigos, con su estado HTTP y cuándo ocurre cada uno, están en Códigos de error. Esta página cubre cómo reaccionar ante un error una vez identificado.

Errores del lado del cliente

Algunas operaciones, como las de archivos, involucran sistemas además de la API de Kivox; por ejemplo, el proveedor de almacenamiento de objetos. Cuando esto aplica, un SDK puede envolver el error en un tipo propio que identifica en qué sistema y en qué etapa ocurrió el fallo, en vez de propagar el error de la API sin ese contexto.

import { KivoxFileError } from "@kivox/sdk/files";

try {
    await client.files.upload({
        workspaceId,
        purpose: "rag",
        filename,
        mimeType,
        data,
    });
} catch (err) {
    if (err instanceof KivoxFileError) {
        console.error(`Fallo en la etapa "${err.stage}" (archivo: ${err.fileId ?? "sin crear"})`);
        console.error(err.message);
    }
    throw err;
}

El detalle de este tipo de error, incluyendo cada valor posible de stage, está en SDK de TypeScript. Cada SDK documenta sus propios tipos de error, si los tiene, en su página bajo SDKs.

Cuándo reintentar

StatusReintentar
400, 401, 403, 404, 412No, sin corregir la causa primero
409Depende del caso; revise message y params
429Sí, con retroceso exponencial
500, 502Sí, con moderación; si persiste, contacte a soporte con el request_id

El detalle de cada código dentro de estas categorías está en Códigos de error.

Idempotencia

Warning

No reintente automáticamente una operación que ya pudo haber ejecutado un efecto externo, como el envío de un mensaje, sin verificar primero si esa operación se completó.

El envío de mensajes admite un encabezado Idempotency-Key para este propósito exacto, descrito en Streaming y eventos.

Para operaciones sobre archivos, el SDK de TypeScript expone un control de reintento separado para las solicitudes hacia el almacenamiento de objetos, distinto del reintento hacia la API de Kivox. Ver SDK de TypeScript.