missing_api_key |
401 |
Envía la cabecera Authorization: Bearer sk_test_... (o sk_live_...). |
invalid_api_key |
401 |
Revisa que la clave esté completa, no revocada y que su prefijo coincida con su ambiente; créala de nuevo en el portal si hace falta. |
insufficient_permissions |
403 |
Usa una clave con el permiso indicado en detail o pide que se lo agreguen en el portal. |
agent_key_mcp_only |
403 |
Las claves de una conexión de agente solo sirven en el servidor MCP, donde aplica su perfil. Para una integración por REST crea una clave de API en el portal. |
not_found |
404 |
Revisa los identificadores de la ruta y que la empresa pertenezca a la cuenta de la clave. |
method_not_allowed |
405 |
Revisa el método HTTP en la referencia de la API. |
invalid_json |
400 |
Envía un cuerpo JSON válido (UTF-8). |
invalid_request |
400 |
Corrige los campos de errors[]: tipo, campo faltante o campo desconocido. Los montos van como texto decimal, por ejemplo “4000.00”. |
unsupported_media_type |
415 |
Envía Content-Type: application/json. |
missing_idempotency_key |
400 |
Envía la cabecera Idempotency-Key con un valor único por documento (por ejemplo un UUID) y repítelo en los reintentos. |
invalid_idempotency_key |
400 |
Usa de 1 a 128 caracteres ASCII visibles, sin espacios. |
invalid_query |
400 |
Corrige los parámetros de errors[]. |
payload_too_large |
413 |
Reduce el cuerpo de la solicitud por debajo del límite. |
idempotency_key_reused |
409 |
Si es un reintento, envía exactamente el mismo cuerpo; si es un documento nuevo, usa otra Idempotency-Key. |
invalid_state |
409 |
Consulta el documento: solo uno rejected se puede corregir y reenviar (resubmit) y solo uno failed se puede reintentar (retry). |
failure_not_retryable |
409 |
Revisa dian.failure_code del documento: invalid_document exige emitir un documento nuevo con el contenido corregido; rendering_failed, not_sent y unclassified los revisa soporte (contacta con el request_id). |
configuration_still_invalid |
409 |
Corrige en el portal lo que indica errors[0].code (el failure_code en que terminaría la transmisión) y vuelve a reintentar; el documento no cambió. |
number_already_used |
409 |
Envía otro número del rango (modo manual) o consulta el documento que ya lo tiene. |
number_in_verification |
409 |
El número lo tiene un documento que espera la verificación de la DIAN (sending o failed con duplicate_unverified): espera a que se resuelva, reintenta su verificación (links.retry) o envía otro número. Solo un rechazo de la DIAN lo libera. |
concurrent_modification |
409 |
Otro proceso cambió el documento al mismo tiempo; consúltalo y repite la operación si sigue aplicando. |
xml_not_available |
409 |
El XML existe cuando el documento se firma; consulta el estado y reintenta cuando deje de estar pending. |
pdf_not_available |
409 |
La representación gráfica se genera con la entrega al comprador, cuando el documento queda accepted (o en contingencia); consulta delivery del documento y reintenta en unos segundos. |
attached_document_not_available |
409 |
El AttachedDocument se genera con la entrega al comprador, cuando el documento queda accepted (o en contingencia); consulta delivery del documento y reintenta en unos segundos. |
document_not_deliverable |
409 |
Solo un documento accepted, o emitido en contingencia DIAN (tipo 04), se entrega al comprador; consulta su estado. |
company_environment_mismatch |
409 |
La empresa no está configurada para el ambiente de la clave; contacta a soporte con el request_id. |
environment_not_configured |
409 |
Completa en el portal la configuración de la empresa en el ambiente de la clave (software, resolución y certificado; en producción, después de terminar la habilitación ante la DIAN) o, mientras tanto, usa una clave sk_test_. |
environment_not_available_in_deployment |
403 |
Este despliegue no atiende el ambiente de la clave (por ejemplo, live en el ambiente de desarrollo). Usa una clave sk_test_ aquí o la URL del despliegue de producción para sk_live_. |
validation_failed |
422 |
Corrige los campos de errors[] según cada message y vuelve a enviar con la misma Idempotency-Key. |
numbering_mode_mismatch |
422 |
En modo manual envía number; en modo automático omítelo y la plataforma asigna el siguiente. |
number_out_of_range |
422 |
Usa un número dentro del rango de la resolución o una resolución con rango disponible. |
resolution_expired |
422 |
Solicita una nueva resolución de numeración a la DIAN y regístrala en el portal. |
resolution_not_yet_valid |
422 |
Espera a la fecha de inicio de la resolución o usa otra vigente. |
resolution_not_found |
422 |
Usa el id de una resolución registrada para la empresa en este ambiente. |
delivery_recipient_required |
422 |
El comprador no tiene correo en el documento: envía email con la dirección a la que debe llegar. |
acquirer_not_found |
404 |
Pide al comprador su nombre (y, si lo quiere, su correo) y envíalos en customer: la consulta es opcional y nunca bloquea la emisión. |
rate_limited |
429 |
Reduce la frecuencia y reintenta después del tiempo de Retry-After. |
not_implemented |
501 |
Esta ruta estará disponible en una versión futura. |
request_timeout |
503 |
Reintenta con la misma Idempotency-Key: si el documento se creó, recibirás el mismo. |
temporarily_unavailable |
503 |
Reintenta en unos segundos con la misma Idempotency-Key. |
acquirer_lookup_unavailable |
503 |
Emite con los datos que dé el comprador (al menos customer.name); la consulta es opcional. Reintenta después de Retry-After si la necesitas. |
contingency_not_found |
404 |
Usa el id que devolvió la declaración de la contingencia (POST .../contingencies) o lista las contingencias de la empresa. |
contingency_already_open |
409 |
Cierra la contingencia abierta (POST .../contingencies/{id}/close) antes de declarar otra; sus facturas de papel se transcriben en ella. |
contingency_already_closed |
409 |
La contingencia ya tiene fecha de fin y su plazo de 48 horas corre desde ella; consulta sus transcripciones pendientes. |
contingency_overlaps |
409 |
Una contingencia nueva empieza cuando termina la anterior o después; revisa started_at. |
paper_outside_contingency |
422 |
Solo se transcriben las facturas de papel expedidas durante la contingencia (anexo 1.9, numeral 12.1): revisa paper.issue_date o la contingencia. |
paper_outside_resolution |
422 |
La fecha de la factura de papel está fuera de la vigencia de su resolución de talonario o papel: revisa paper.issue_date y paper.resolution_id. |
paper_already_transcribed |
409 |
Ese papel ya tiene su transcripción (ver detail): consúltala; si es un reintento, envía exactamente el mismo cuerpo. |
resolution_kind_mismatch |
422 |
Las facturas electrónicas usan una resolución de facturación electrónica; la transcripción de un papel (tipo 03) usa la resolución de talonario o papel con que se numeró. |
note_series_not_configured |
409 |
La serie de notas crédito o débito de la empresa no está configurada: su prefijo por defecto chocó con otro prefijo. Un administrador debe elegir otro prefijo en el portal. |
conflict |
409 |
Revisa detail: el recurso ya existe o cambió; consúltalo y repite si sigue aplicando. |
certificate_unreadable |
422 |
Revisa que el archivo sea el .p12 (PKCS#12) con su clave privada y que la contraseña sea la correcta. |
certificate_expired |
422 |
Sube un certificado de firma vigente; el vencimiento está en detail. |
certificate_not_yet_valid |
422 |
Espera a la fecha de inicio de su vigencia (en detail) o sube otro certificado. |
software_not_configured |
409 |
Configura primero el software del ambiente (SoftwareID, PIN y, en habilitación, TestSetId) en PUT .../environments/{environment}/software. |
habilitation_not_ready |
409 |
Completa lo que indica errors[] (software con TestSetId, certificado y resolución de habilitación vigente) y vuelve a iniciar el set de habilitación. |
habilitation_required |
409 |
Aprueba el set de habilitación de la DIAN en el asistente de habilitación del portal (/habilitacion) con el software de habilitación vigente y vuelve a emitir con la misma Idempotency-Key: no se consumió ningún número. Cambiar el software de habilitación exige aprobar el set de nuevo; renovar el certificado no. Reintentar o reenviar un documento ya creado no pasa por esta regla. |
dian_unavailable |
503 |
Reintenta en unos minutos; nada se cambió. |
draft_not_found |
404 |
Usa el draft_id que devolvió la preparación del borrador; un borrador descartado se borra 90 días después. |
draft_already_approved |
409 |
El borrador ya se emitió: consulta su documento (document_id); un borrador aprobado no se descarta. |
draft_discarded |
409 |
Una persona descartó este borrador: no se emitió nada. Si el documento sigue haciendo falta, el agente prepara otro con otra clave de idempotencia. |
agent_daily_limit_reached |
409 |
El agente que preparó el borrador ya creó hoy los documentos que su tope diario permite: apruébalo mañana o sube el tope en Agentes (MCP). |
sandbox_quota_exceeded |
429 |
La empresa emitió los documentos del mes que permite el sandbox (1.000): espera al próximo mes; reiniciar el sandbox no devuelve la cuota. Para más volumen, prueba en habilitación (sk_test_). |
sandbox_rate_limited |
429 |
El sandbox acepta 60 escrituras por minuto y empresa: espera el tiempo de Retry-After. No hagas pruebas de carga en el sandbox. |
unknown_sandbox_scenario |
422 |
Usa un id del catálogo (GET /v1/sandbox/scenarios) en la cabecera Foliios-Sandbox-Scenario o en la nota [sandbox:<id>]. |
sandbox_scenario_not_allowed |
422 |
Los escenarios solo aplican con claves sk_sandbox_: quita la cabecera Foliios-Sandbox-Scenario en habilitación y producción. |
sandbox_only |
403 |
Esta ruta es del sandbox: llámala con una clave sk_sandbox_. |
sandbox_disabled |
503 |
El sandbox está apagado por operación (abuso o mantenimiento); vuelve a intentar más tarde. test y live no se afectan. |
temporary_key_limit_reached |
409 |
La cuenta ya tiene las claves temporales del sandbox que permite el límite (10 vivas): revoca alguna o espera a que venzan (24 horas). |
sandbox_managed |
409 |
El sandbox usa la resolución, el software y el certificado de prueba de foliios: no hay nada que configurar a mano allí. |
overdraft_limit_reached |
402 |
Recarga documentos desde el portal (purchase_url, si viene) o escribe al contacto indicado (contact_url, contact_email) y repite con la misma Idempotency-Key: no se consumió ningún número. Las notas, las transcripciones y los reintentos no se rechazan por saldo. |
webhook_signature_invalid |
401 |
La firma no corresponde al cuerpo recibido: la notificación se descartó sin cambiar nada. Solo el proveedor de pagos la conoce. |
catalog_changed |
409 |
La bolsa cambió de precio, de unidades o se retiró después de que la viste. Si viene bag_id, muestra al comprador la bolsa vigente (units, price, bag_version) y repite con ese bag_version; si no, vuelve a leer el catálogo. |
checkout_unavailable |
409 |
Ahora no hay compra en línea: el cobro está desactivado o no hay bolsas a la venta. Escribe al contacto del catálogo (GET /v1/billing/catalog). |
habilitation_resolution_manual |
409 |
La sincronización (GetNumberingRange) trae solo las resoluciones de producción: en habilitación registra a mano la resolución SETP, copiada del catálogo de habilitación de la DIAN. |
sandbox_certificate_not_allowed |
422 |
El certificado de prueba de foliios no sirve en habilitación ni producción: sube el certificado de firma de la empresa, emitido por una entidad acreditada por la ONAC. |
reset_not_confirmed |
422 |
Envía en confirmation el id de la empresa (cmp_...) para confirmar que quieres borrar sus datos del sandbox. |
internal_error |
500 |
Reintenta con la misma Idempotency-Key; si persiste, contacta a soporte con el request_id. |
