Todos los errores tienen el mismo formato, con el mensaje en español. detalles es opcional y trae información adicional, por ejemplo qué campos fallaron la validación.
{
"error": {
"codigo": "validacion",
"mensaje": "El campo items debe tener al menos un elemento.",
"detalles": [ { "campo": "items", "mensaje": "Debe tener al menos 1 elemento" } ]
}
}Códigos#
| HTTP | codigo | Qué hacer |
|---|---|---|
| 400 | validacion | Corrige los campos indicados en detalles y vuelve a intentar. |
| 401 | no_autorizado | Revisa la API key y el header Authorization. |
| 403 | prohibido | Tu key no tiene acceso a ese recurso o a esa empresa. |
| 404 | no_encontrado | El recurso no existe o es de otra empresa. |
| 409 | conflicto | El recurso ya existe o choca con otro (por ejemplo, un idExterno repetido). |
| 409 | secuencia_agotada | Se acabó el rango de e-NCF. Registra uno nuevo en /v1/sequences. |
| 409 | idempotencia | Usaste la misma Idempotency-Key con un cuerpo distinto. |
| 422 | certificado_faltante | Sube tu certificado digital antes de emitir en ese ambiente. |
| 422 | empresa_incompleta | Faltan datos de la empresa. Complétalos con PATCH /v1/company. |
| 429 | limite_excedido | Superaste el límite de uso. Espera los segundos del header Retry-After. |
| 502 | dgii_no_disponible | La DGII no responde. El e-CF queda en cola y se reintenta solo (contingencia). |
Contingencia#
Si la DGII no está disponible, no pierdes la factura: Firmo responde 502 con dgii_no_disponible, deja el e-CF en cola y lo reintenta. Cuando haya resultado, te llega el webhook correspondiente. No vuelvas a emitirlo: si reintentas, usa la misma Idempotency-Key.