Errores e idempotencia - Doconda

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

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

⌘I