> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doconda.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

<CodeGroup>
  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  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 para tus logs: en inglés, o en español con language: "es"
    console.log(e.errors)    // en 422: qué campo está mal y por qué
    console.log(e.requestId) // dánoslo si escribes a soporte
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  from doconda import DocondaError

  try:
      doconda.documents.create(format="docx", prompt="Memo para el equipo")
  except DocondaError as e:
      print(e.status)  # 402
      print(e.code)  # "insufficient_balance": estable, úsalo para decidir
      print(str(e))  # explicación para tus logs: en inglés, o en español con language="es"
      print(e.errors)  # en 422: qué campo está mal y por qué
      print(e.request_id)  # dánoslo si escribes a soporte
  ```
</CodeGroup>

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. |
| `not_found` | Ese documento no es de este proyecto. |

La lista completa está en [errores](/es/guides/errors).

Un documento que **falla al procesarse** no es una excepción: `create` lo devuelve con `status: "failed"` y
`doc.error`. Uno cancelado tampoco: vuelve con `status: "canceled"`. Ninguno de los dos se cobra.

## Reintentos

El SDK reintenta solo los fallos de red, `429` y `5xx`, esperando cada vez un poco más.
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 (`idempotencyKey`; en Python, `idempotency_key`), estable para esa operación:

<CodeGroup>
  ```ts TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  await doconda.documents.create(
    { format: "docx", prompt: "Carta de bienvenida para un cliente nuevo" },
    { idempotencyKey: `carta-bienvenida-${userId}` },
  )
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  doconda.documents.create(
      format="docx",
      prompt="Carta de bienvenida para un cliente nuevo",
      idempotency_key=f"carta-bienvenida-{user_id}",
  )
  ```
</CodeGroup>

La API la recuerda 24 horas.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.