Skip to main content

​
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
}
CampoTipoDescripción
codigostringIdentificador del error. Vea el catálogo más abajo.
mensajestringDescripción del error en español, pensada para mostrarse o registrarse.
masInformacionstringURL de referencia con más contexto.
severidadnumber0 Sugerencia, 1 Advertencia, 2 Error, 3 Fatal. La gran mayoría de errores de solicitud usan 2.

​
Convenciones de código HTTP

Código HTTPCuándo se usa
200 OKSolicitud exitosa (incluye creación de DTE, anulación, consultas).
204 No ContentOperación exitosa sin cuerpo de respuesta (por ejemplo, enviar un DTE por correo).
400 Bad RequestLa 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 UnauthorizedToken ausente, inválido o expirado.
403 ForbiddenEl usuario autenticado no tiene permisos sobre el recurso solicitado.
404 Not FoundReservado para un conjunto más reducido de rutas nuevas sin equivalente histórico.
429 Too Many RequestsSe excedió el límite de solicitudes. Vea límites de tasa.

​
Catálogo de códigos conocidos

CódigoHTTPSignificado
FEG_VALIDATION_ERROR400Error de validación en los campos enviados. El detalle específico viaja en mensaje (vea la sección siguiente).
FEG_DET_OBTE_INEX400El documento solicitado no existe o no tiene permisos suficientes para obtenerlo.
FEG_DTE_INVALID_OPERATION400La operación solicitada no es válida para este DTE.
FEG_DTE_CERTIFICATION_ERROR400La autoridad fiscal (SAT/MH/DGII, vía el certificador) rechazó el documento durante la certificación. Vea Errores de certificación.
FEG_DTE_INVALID_STATE400El DTE no está en el estado requerido para la operación (por ejemplo, intentar anular un documento ya anulado).
FEG_INVALID_NIT400El NIT o identificador fiscal indicado no es válido.
FEG_INVALID_TAX_CONFIG400Configuración de impuestos inválida en el documento.
FEG_BUSINESS_RULE_VIOLATION400Se incumplió una regla de negocio. El detalle viaja en mensaje.
FEG_NOT_FOUND404Recurso no encontrado (rutas nuevas sin equivalente histórico).
FEG_UNAUTHORIZED401No autorizado para acceder al recurso.
FEG_FORBIDDEN403Sin permisos para acceder al recurso.
FEG_NO_CUENTAS400El usuario autenticado no tiene ninguna cuenta asignada.
FEG_CUENTA_INVALID400No se pudo determinar la cuenta sobre la cual operar — indique idCuenta explícitamente.
FEG_DTE_CREA_001400Documento duplicado: ya existe un DTE con el mismo numeroTransaccion para la cuenta.
FEG_DTE_CREA_010400El documento original referenciado por idDteOriginal no existe (aplica a notaCredito/notaDebito).
FEG_DTE_CREA_018400Impuesto IDB: el código de unidad gravable indicado no es válido para bebidas. Vea Impuestos.
LOT-INVEXC-2400Carga masiva: el archivo no es un .xlsx válido (el formato .xls antiguo no es procesable). Vea Carga masiva.
LOT-INVEXC-3 … LOT-INVEXC-5400Carga masiva: el contenido del Excel no pudo interpretarse (hoja, encabezados o filas inválidos). Vea Carga masiva.
1000400Error 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:
EscenarioPaísMensaje (mensaje)
motivoExencionIva no reconocidoTodos”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 datosExportacionTodos”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 codigoUnidadGravableTodos”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.