Manejo de errores

Formato de respuesta de error

Salvo POST /token (que sigue el formato estándar de OAuth2 — vea Autenticación), todos los errores del API responden con el mismo sobre JSON:

{
  "codigo": "FEG_VALIDATION_ERROR",
  "mensaje": "Debe incluir al menos un ítem.",
  "masInformacion": "https://developer.fegora.com",
  "severidad": 2
}

Campo	Tipo	Descripción
`codigo`	string	Identificador del error. Vea el catálogo más abajo.
`mensaje`	string	Descripción del error en español, pensada para mostrarse o registrarse.
`masInformacion`	string	URL de referencia con más contexto.
`severidad`	number	`0` Sugerencia, `1` Advertencia, `2` Error, `3` Fatal. La gran mayoría de errores de solicitud usan `2`.

Convenciones de código HTTP

Código HTTP	Cuándo se usa
`200 OK`	Solicitud exitosa (incluye creación de DTE, anulación, consultas).
`204 No Content`	Operación exitosa sin cuerpo de respuesta (por ejemplo, enviar un DTE por correo).
`400 Bad Request`	La gran mayoría de errores: validación de campos, reglas de negocio, y también condiciones como “documento no encontrado” — por compatibilidad con el comportamiento histórico del API, varios casos que normalmente serían `404` se devuelven como `400` con un `codigo` específico.
`401 Unauthorized`	Token ausente, inválido o expirado.
`403 Forbidden`	El usuario autenticado no tiene permisos sobre el recurso solicitado.
`404 Not Found`	Reservado para un conjunto más reducido de rutas nuevas sin equivalente histórico.
`429 Too Many Requests`	Se excedió el límite de solicitudes. Vea límites de tasa.

Catálogo de códigos conocidos

Código	HTTP	Significado
`FEG_VALIDATION_ERROR`	400	Error de validación en los campos enviados. El detalle específico viaja en `mensaje` (vea la sección siguiente).
`FEG_DET_OBTE_INEX`	400	El documento solicitado no existe o no tiene permisos suficientes para obtenerlo.
`FEG_DTE_INVALID_OPERATION`	400	La operación solicitada no es válida para este DTE.
`FEG_DTE_CERTIFICATION_ERROR`	400	La autoridad fiscal (SAT/MH/DGII, vía el certificador) rechazó el documento durante la certificación. Vea Errores de certificación.
`FEG_DTE_INVALID_STATE`	400	El DTE no está en el estado requerido para la operación (por ejemplo, intentar anular un documento ya anulado).
`FEG_INVALID_NIT`	400	El NIT o identificador fiscal indicado no es válido.
`FEG_INVALID_TAX_CONFIG`	400	Configuración de impuestos inválida en el documento.
`FEG_BUSINESS_RULE_VIOLATION`	400	Se incumplió una regla de negocio. El detalle viaja en `mensaje`.
`FEG_NOT_FOUND`	404	Recurso no encontrado (rutas nuevas sin equivalente histórico).
`FEG_UNAUTHORIZED`	401	No autorizado para acceder al recurso.
`FEG_FORBIDDEN`	403	Sin permisos para acceder al recurso.
`FEG_NO_CUENTAS`	400	El usuario autenticado no tiene ninguna cuenta asignada.
`FEG_CUENTA_INVALID`	400	No se pudo determinar la cuenta sobre la cual operar — indique `idCuenta` explícitamente.
`FEG_DTE_CREA_001`	400	Documento duplicado: ya existe un DTE con el mismo `numeroTransaccion` para la cuenta.
`FEG_DTE_CREA_010`	400	El documento original referenciado por `idDteOriginal` no existe (aplica a `notaCredito`/`notaDebito`).
`FEG_DTE_CREA_018`	400	Impuesto IDB: el código de unidad gravable indicado no es válido para bebidas. Vea Impuestos.
`LOT-INVEXC-2`	400	Carga masiva: el archivo no es un `.xlsx` válido (el formato `.xls` antiguo no es procesable). Vea Carga masiva.
`LOT-INVEXC-3` … `LOT-INVEXC-5`	400	Carga masiva: el contenido del Excel no pudo interpretarse (hoja, encabezados o filas inválidos). Vea Carga masiva.
`1000`	400	Error interno no clasificado. En producción el mensaje no expone detalles internos.

Validaciones específicas de creación de DTE (`POST /dte`)

Varias reglas de POST /dte — algunas específicas de un país — llevan un identificador interno para rastrear cuál regla falló. Actualmente ese identificador no se refleja en el campo codigo de la respuesta: todas viajan bajo codigo: "FEG_VALIDATION_ERROR", y el mensaje es lo único que distingue el escenario. La tabla siguiente sirve para reconocer cada caso por su mensaje:

Escenario	País	Mensaje (`mensaje`)
`motivoExencionIva` no reconocido	Todos	”El motivo de exención de IVA no es reconocido.”
Receptor con datos de CCF/FSE (`MH_NRC` o `MH_CODIGO_ACTIVIDAD`) sin `NUMERO_SECUENCIAL`	🇸🇻 El Salvador	”El dato NUMERO_SECUENCIAL es requerido para documentos SV con receptor CCF/FSE.”
`tipo: "facturaExportacion"` o `esExportacion: true` sin el bloque `datosExportacion`	Todos	”El DTE de exportacion requiere el campo datosExportacion”
Exportación a Consumidor Final (`receptor.id: "CF"`) por Q2,500 o más	🇬🇹 Guatemala	”Acuerdo gubernativo 12-2023: las exportaciones a Consumidor Final no pueden tener monto mayor o igual a Q2,500.”
Impuesto `IVA` explícito en `items[].impuestos` sin `codigoUnidadGravable`	Todos	”El impuesto IVA explícito requiere codigoUnidadGravable.”

Errores de certificación (SAT / MH / DGII)

Cuando el documento pasa las validaciones del API pero la autoridad fiscal (a través del certificador de la cuenta: Digifact, Infile, Megaprint, etc.) lo rechaza, el API responde 400 con codigo: "FEG_DTE_CERTIFICATION_ERROR". El mensaje incluye el código y la descripción que devolvió el certificador, por ejemplo:

{
  "codigo": "FEG_DTE_CERTIFICATION_ERROR",
  "mensaje": "Certificación falló: 9026: Falló la validación de algunos escenarios.",
  "masInformacion": "https://developer.fegora.com",
  "severidad": 2
}

El contenido exacto del mensaje varía según el certificador y el país — algunos certificadores devuelven además una lista de eventos de consistencia con el detalle campo por campo del rechazo, que hoy es usada principalmente para diagnóstico interno.

Introducción

Documentos DTE

Guías por país

Manejo de errores

Formato de respuesta de error

Convenciones de código HTTP

Catálogo de códigos conocidos

Validaciones específicas de creación de DTE (`POST /dte`)

Errores de certificación (SAT / MH / DGII)

​Formato de respuesta de error

​Convenciones de código HTTP

​Catálogo de códigos conocidos

​Validaciones específicas de creación de DTE (POST /dte)

​Errores de certificación (SAT / MH / DGII)

Formato de respuesta de error

Convenciones de código HTTP

Catálogo de códigos conocidos

Validaciones específicas de creación de DTE (`POST /dte`)

Errores de certificación (SAT / MH / DGII)