> ## 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={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "type": "https://docs.doconda.com/guides/errors#input_invalid",
  "title": "The request is not valid.",
  "status": 422,
  "code": "input_invalid",
  "request_id": "req_…",
  "errors": [{ "path": "/prompt", "message": "Too small: expected string to have >=3 characters" }]
}
```

| Código | HTTP | Qué hacer |
| - | - | - |
| `input_invalid` | 422 | Corrige la petición; `errors[].path` señala el campo y `message` dice qué está mal. Un fichero en base64 de más de 20 MB también da este error. |
| `unauthorized` | 401 | Envía `Authorization: Bearer ak_…` con una key válida. |
| `region_mismatch` | 401 | La key es de un proyecto de otra región: usa la URL de esa región (`ak_eu_…` → `api.eu.doconda.com`). |
| `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. |
| `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 otro proyecto u otra organización). |
| `file_rejected` | 422 | El archivo no es válido: tipo no admitido o con macros (`.docm`, `.pptm`, `.xlsm`). |
| `file_unreachable` | 422 | No pudimos descargar la URL que pasaste: tiene que ser pública y responder con el fichero. |
| `file_too_large` | 413 | Los archivos, por `multipart` o por URL, pueden ocupar hasta 20 MB. |
| `fst_…` | 400, 413 o 415 | No pudimos leer la petición: JSON no válido o vacío, `Content-Type` no admitido o cuerpo demasiado grande (`fst_err_ctp_body_too_large`, por ejemplo con varios ficheros grandes en base64 a la vez: súbelos antes con `POST /files`). El `title` dice qué. |
| `document_has_no_file` | 409 | El `doc_…` que pasaste como fichero no tiene un Word, PowerPoint, Excel o PDF (si aún se está haciendo, espera a que termine). |
| `document_not_finished` | 409 | El documento aún se está haciendo y no se puede borrar: cancélalo antes. |
| `revision_conflict` | 409 | Alguien guardó el archivo después de que lo abrieras: ábrelo de nuevo. |
| `document_busy` | 409 | El documento se está haciendo o guardando. |
| `not_editable` | 409 | El documento no tiene un Word, Excel, PowerPoint o PDF que guardar. |
| `file_format_mismatch` | 422 | La versión no tiene el formato del documento. |
| `webhook_url_invalid` | 422 | La URL del webhook tiene que ser `https` y pública. |
| `report_not_ready` | 409 | El informe existe cuando el documento se entrega (`ready`, `ready_with_warnings` o `needs_review`): espera o sigue sus eventos. Un documento `failed` o `canceled` no tiene informe y sigue respondiendo esto. |
| `content_deleted` | 410 | Acabó la [retención](/es/guides/retention) del documento: su contenido se ha borrado. |
| `retention_none_shared` | 422 | Con `retention: "none"` no se guarda nada: 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`. |

## Idioma de los mensajes

`title`, `errors[].message` y todo texto que Doconda escribe sobre un documento (los `issues[].message` y las notas del
informe, `style_unsupported`, el `error.message` de un documento fallido) siguen la cabecera `Accept-Language` de la
petición: en español con `es`, en inglés con cualquier otro valor y también si falta. Los textos de un documento se
escriben al crearlo, en el idioma de la petición que lo creó. Los SDK aceptan `language: "es"` (TypeScript) o
`language="es"` (Python). Los códigos no cambian con el idioma: decide con `code`, no con el texto.

## 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, un PDF de más de 50 páginas para revisar o editar). 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 en `fast` o siendo `.doc`, `.ppt` o `.xls` (más de 3.000 párrafos, celdas o líneas). |
| `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`. |
| `request_refused` | La petición busca engañar o hacer daño (falsificaciones, suplantaciones, páginas que piden contraseñas o tarjetas). |
| `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; los eventos `edit.operation_rejected` dicen por qué (un documento fallido no tiene informe). |
| `pdf_not_convertible` | Para hacer en un PDF algo más que cambiar texto hay que pasarlo a Word, y este PDF no se pudo convertir. |
| `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. |
| `page_too_long` | La página del artifact es tan larga que el modelo no pudo terminarla: pide una más sencilla o divídela en dos. No se cobra. |
| `processing_failed` | No pudimos procesarlo tras varios intentos. Reintenta más tarde. |

## Idempotencia

Envía `Idempotency-Key` en `POST /documents` (los demás `POST` no la usan). 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.