Errores e idempotencia

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

{
  "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 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.

Empezar

Operaciones

Conceptos

Tutoriales

Cuenta

Más recursos

Errores e idempotencia

Idioma de los mensajes

Cuando un documento falla

Idempotencia

​Idioma de los mensajes

​Cuando un documento falla

​Idempotencia

Idioma de los mensajes

Cuando un documento falla

Idempotencia