> ## 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 e idempotencia

> Errores RFC 9457 y reintentos seguros.

Los errores son `application/problem+json` con un `code` estable:

```json theme={null}
{
  "type": "https://docs.doconda.com/errors/input_invalid",
  "title": "The request is not valid.",
  "status": 422,
  "code": "input_invalid",
  "request_id": "req_…",
  "errors": [{ "path": "/style/font_size", "message": "must be <= 16" }]
}
```

| Código | HTTP | Qué hacer |
| - | - | - |
| `input_invalid` | 422 | Corrige la petición; `errors[].path` señala el campo y `message` dice qué falta. |
| `unauthorized` | 401 | Envía `Authorization: Bearer ak_…` con una key válida. |
| `insufficient_balance` | 402 | No te queda saldo para este documento: recarga en el panel (o activa la recarga automática). |
| `session_required` | 403 | Esa ruta es solo del panel; con una API key no se puede usar. |
| `region_mismatch` | 401 | El proyecto de la key es de otra región: usa la URL de su región. |
| `link_expired` | 410 | El enlace del artifact ha caducado: pide otro con `GET /documents/{id}/outputs`. |
| `rate_limited` | 429 | Más de 120 documentos por minuto en la organización, o demasiadas lecturas o escrituras en un artifact. Espera un poco y repite. |
| `not_an_artifact` | 409 | Solo los documentos con `format: "artifact"` guardan datos. |
| `record_too_large` | 413 | Un registro de `doconda.db` pasa de 16 KB. |
| `too_many_records` | 409 | El artifact ya tiene 5.000 registros. |
| `not_found` | 404 | El documento o el archivo no existe (o es de otra organización). |
| `file_rejected` | 422 | El archivo no es válido: tipo no admitido o con macros (`.docm`, `.pptm`, `.xlsm`). |
| `file_too_large` | 413 | Los archivos pueden ocupar hasta 20 MB. |
| `report_not_ready` | 409 | El informe existe cuando el documento termina: espera o sigue sus eventos. |
| `content_deleted` | 410 | Pediste `store: false` y ya pasaron los 15 minutos: el contenido se ha borrado. |
| `project_does_not_store` | 422 | El proyecto no guarda contenido: un artifact solo puede ser `artifact.storage: "local"`. |
| `artifact_is_local` | 409 | Ese artifact guarda sus datos en el navegador de cada visitante: Doconda no los tiene. |
| `events_expired` | 410 | Los eventos se guardan 7 días: lee el documento con `GET /documents/{id}`. |
| `idempotency_key_reused` | 422 | Usaste la misma `Idempotency-Key` con otra petición distinta. |
| `idempotency_request_in_progress` | 409 | La primera petición con esa key aún no ha terminado: reintenta en unos segundos. |
| `feature_unavailable` | 501 | La IA no está activada en este despliegue (afecta a `prompt`, editar y el estilo en texto). |
| `internal_error` | 500 | Fallo nuestro. Reintenta; si persiste, escríbenos con el `request_id`. |

## Cuando un documento falla

Si el problema aparece mientras se procesa, la petición ya fue aceptada: el documento termina con `status: "failed"` y `error.code` explica por qué. No se cobra.

| `error.code` | Qué pasó |
| - | - |
| `content_empty` | El contenido no tiene nada que mostrar (títulos, texto, listas o tablas). |
| `file_rejected` | Al abrir tu archivo encontramos algo que no procesamos (macros, estructura anómala, XML no permitido, PDF con contraseña). El mensaje dice qué. |
| `docx_invalid` | El archivo no es un Word válido. |
| `file_not_found` | El archivo se borró antes de procesarlo. |
| `document_too_long` | El documento es demasiado largo para editarlo (unas 50 páginas). |
| `format_unclear` | No dijiste `format` y de tu `prompt` no queda claro si quieres un Word, un PDF, un PowerPoint, un Excel o un artifact: dilo en `format`. |
| `edit_not_understood` | No supimos convertir lo que pediste en cambios concretos: dilo de forma más precisa. |
| `edit_not_applied` | Ninguno de los cambios pedidos se pudo aplicar a ese documento; el informe dice por qué. |
| `source_unreadable` | No pudimos leer uno de los ficheros de `sources`. |
| `generation_blocked` | El modelo no quiso escribir ese documento: reformula la petición. |
| `page_too_large` | La página del artifact supera el tamaño máximo. |
| `processing_failed` | No pudimos procesarlo tras varios intentos. Reintenta más tarde. |

## Idempotencia

Envía `Idempotency-Key` en `POST /documents`. Si repites la petición con la misma key y el mismo cuerpo (durante 24 h, en el mismo proyecto), recibes el mismo documento sin crear otro ni cobrarlo dos veces. Con otro cuerpo, `422 idempotency_key_reused`.


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