Errores y rechazos del MH

Todos los errores usan el estándar RFC 9457 con el tipo de contenido application/problem+json y mensajes en español.

422 Unprocessable Entity

{
  "type": "https://sudte.com/errors/validacion",
  "title": "Datos inválidos",
  "status": 422,
  "detail": "Revise los campos indicados.",
  "request_id": "req_01JA2N4C8F6H8K0M2P4R6T8V0X",
  "errors": [
    { "path": "/receiver/nrc", "message": "El NRC es obligatorio en un crédito fiscal." },
    { "path": "/items/0/unit_price", "message": "Debe ser un monto decimal mayor que cero." }
  ]
}

Campo	Contenido
type	URL estable que identifica el tipo de error. Úsala en tu código en lugar del texto.
title · detail	Resumen y explicación para mostrar a una persona.
status	El mismo código HTTP de la respuesta.
request_id	Identificador de la solicitud. Inclúyelo al escribir a soporte.
errors[]	Campos con error: path (puntero JSON) y message. Se devuelven todos juntos.
mh	Solo en rechazos del MH: codigoMsg, descripcionMsg y observaciones originales.

Rechazo del Ministerio de Hacienda

Cuando el MH rechaza un documento, la API responde 422 con tipo mh-rechazo. El documento queda guardado en estado rejected con su código de generación y número de control:

{
  "type": "https://sudte.com/errors/mh-rechazo",
  "title": "Rechazado por el Ministerio de Hacienda",
  "status": 422,
  "detail": "El MH rechazó el documento: [receptor.nrc] FORMATO NO VALIDO. Envíe el NRC sin guiones ni espacios.",
  "document_id": "doc_01JA2M7R5N3P8Q4S6T0V2W4X6Y",
  "generation_code": "5D0C2B1A-7E3F-4A9B-8C6D-1E2F3A4B5C6D",
  "control_number": "DTE-03-M001P001-000000000000058",
  "mh": {
    "codigoMsg": "006",
    "descripcionMsg": "[receptor.nrc] FORMATO NO VALIDO",
    "observaciones": []
  },
  "errors": [{ "path": "dte.receptor.nrc", "message": "[receptor.nrc] FORMATO NO VALIDO" }]
}

Corrige los datos y reenvía con POST /v1/documents/{id}/retry dentro de las 24 horas siguientes, conservando el mismo código de generación.

Tipos de error de la API

validacion · 422 Datos inválidos

Cuándo: Uno o más campos no cumplen las reglas del tipo de DTE o del esquema oficial del MH: faltan datos del receptor, montos mal formados, códigos de catálogo inexistentes, pagos que no suman el total, establecimiento o punto de venta no registrados, fecha de emisión fuera de la holgura de 30 minutos o un plazo vencido.

Qué hacer: Revisa errors[]: cada elemento trae la ruta JSON del campo (path) y el motivo, y se devuelven todos juntos. No se firmó, no se transmitió ni se consumió un número de control. Reenvía el cuerpo corregido con una Idempotency-Key nueva.

mh-rechazo · 422 Rechazado por el Ministerio de Hacienda

Cuándo: El MH respondió RECHAZADO. El problema incluye el objeto mh con codigoMsg, descripcionMsg y observaciones tal como los envió el MH; el documento queda en estado rejected y se envía el webhook document.rejected.

Qué hacer: Corrige y reintenta con POST /documents/{id}/retry dentro de las 24 horas: sudte conserva el código de generación, como exige la Normativa. Consulta la tabla de códigos del MH más abajo.

mh-credenciales · 422 Credenciales del MH inválidas

Cuándo: El certificado no abre con la clave indicada, no corresponde al NIT del emisor o al ambiente, o el MH rechazó el usuario o la contraseña de la API.

Qué hacer: Vuelve a cargar las credenciales del ambiente correcto. sudte no reintenta el login con una contraseña rechazada porque el MH bloquea el usuario tras varios intentos fallidos.

estado-invalido · 409 Operación no permitida en el estado actual

Cuándo: Por ejemplo, invalidar un documento que todavía no tiene sello (solo se invalida en estado processed), emitir una nota sobre un crédito fiscal no sellado o reintentar un documento ya procesado.

Qué hacer: Consulta el documento con GET /documents/{id} y espera el estado adecuado.

idempotencia-conflicto · 409 La Idempotency-Key ya se usó con otro contenido

Cuándo: Reutilizaste una clave con un cuerpo diferente al de la solicitud original.

Qué hacer: Si es la misma operación, reenvía exactamente el mismo cuerpo. Si es otra operación, usa una clave nueva.

numeracion-agotada · 409 Numeración agotada

Cuándo: Se agotó el correlativo de 15 dígitos del año para el establecimiento. En la práctica no debería ocurrir.

Qué hacer: Escríbenos a soporte de inmediato.

solicitud-invalida · 400 Solicitud inválida

Cuándo: Falta la cabecera Idempotency-Key en un POST, el cuerpo no es JSON válido o un parámetro tiene un formato incorrecto.

Qué hacer: Envía JSON válido y una Idempotency-Key única por operación de negocio (por ejemplo, el identificador de la venta en tu sistema).

no-autenticado · 401 No autenticado

Cuándo: No enviaste la cabecera Authorization: Bearer, la API key fue revocada o tiene un formato incorrecto.

Qué hacer: Envía una API key vigente. Crea o revoca keys desde el panel.

credenciales-invalidas · 401 Correo o contraseña incorrectos

Cuándo: Inicio de sesión en el panel con datos que no coinciden.

Qué hacer: Verifica tus datos o recupera tu contraseña. Tras varios intentos fallidos el acceso se limita temporalmente.

otp-requerido · 403 Se requiere el código de verificación

Cuándo: El usuario tiene activado el segundo factor y no envió el código, o el código es incorrecto.

Qué hacer: Envía el código de 6 dígitos de tu aplicación de autenticación.

prohibido · 403 Sin permiso

Cuándo: La API key está limitada a otros emisores o no tiene el permiso necesario para la operación.

Qué hacer: Usa una key con acceso al emisor o amplía sus permisos desde el panel.

no-encontrado · 404 No encontrado

Cuándo: El recurso no existe o pertenece a otra cuenta o a otro ambiente (una key sk_test_ no ve documentos de producción).

Qué hacer: Verifica el identificador y el ambiente de la API key.

limite-excedido · 429 Demasiadas solicitudes

Cuándo: Superaste el límite de velocidad de tu API key o de tu plan.

Qué hacer: Espera los segundos indicados en la cabecera Retry-After y reintenta con espera exponencial.

error-interno · 500 Error interno

Cuándo: Ocurrió un problema inesperado de nuestro lado.

Qué hacer: Reintenta con la misma Idempotency-Key (es seguro). Si persiste, escríbenos con el request_id.

no-implementado · 501 No implementado

Cuándo: La operación existe en el contrato pero todavía no está disponible.

Qué hacer: Revisa el registro de cambios o escríbenos para conocer la fecha estimada.

no-disponible · 503 Servicio no disponible

Cuándo: Una operación que necesita respuesta inmediata del MH (por ejemplo, una invalidación) no obtuvo respuesta. Al emitir, en cambio, recibes 202 y el documento sigue su curso.

Qué hacer: Reintenta en unos minutos con la misma Idempotency-Key. Revisa el estado del MH en sudte.com/estado.

Códigos de respuesta del MH

Códigos del servicio de recepción según el manual técnico de integración del MH, versión 2.0. El MH devuelve el campo afectado entre corchetes en descripcionMsg; en las respuestas a veces aparecen con ceros a la izquierda (006).

Código	Mensaje del MH	Causa habitual
1	RECIBIDO	—
2	RECIBIDO CON OBSERVACIONES	—
3	[campo] VALOR NO VALIDO	Un valor no está en el catálogo o no es válido para ese campo. Revisa el campo indicado entre corchetes.
4	[campo] YA EXISTE UN REGISTRO CON ESE VALOR	Ya existe un documento con ese código de generación o número de control. Antes de reenviar, consulta el estado: puede que ya esté sellado.
5	[campo] DEBE PROPORCIONAR UN VALOR	—
6	[campo] FORMATO NO VALIDO	Formato incorrecto: NIT o NRC con guiones o espacios, DUI en un campo de NIT, fecha u hora mal formada.
7	[campo] VALOR NO ES PERMITIDO	—
8	[campo] NO CORRESPONDE A CONTRIBUYENTE	—
9	[campo] NIT CONTRIBUYENTE NO EXISTE	—
10	[campo] CONTRIBUYENTE NO SE ENCUENTRA ACTIVO	—
11	[campo] NO ES CONTRIBUYENTE IVA	—
12	[campo] NO EXISTE EVENTO DE CONTINGENCIA	—
13	[campo] NO ESTA ENTRE PERIODO REPORTADO EN EVENTO DE CONTINGENCIA	—
14	[campo] NO EXISTE UN REGISTRO CON ESTE DATO	—
15	[campo] DOCUMENTO SE ENCUENTRA INVALIDADO	El documento relacionado fue invalidado; no se le pueden aplicar notas ni eventos.
16	[campo] MONTO ES MAYOR AL DOCUMENTO RELACIONADO	La nota de crédito supera el monto del documento relacionado.
17	[campo] FECHA NO ES CORRECTA	—
18	[campo] FECHA FUERA DE PLAZO PERMITIDO	El evento o documento se transmite fuera del plazo permitido por la Normativa.
19	[campo] ERROR EN CORRELATIVO	—
20	[campo] CALCULO INCORRECTO	Los totales no coinciden con el cálculo del MH: suele ser IVA sobre precios que ya lo incluyen, redondeo con decimales binarios o descuentos aplicados dos veces.
21	[campo] NO SE PUEDE VALIDAR CAMPO	—
22	[firma] SERVICIO DE VALIDACION DE FIRMA NO DISPONIBLE	—
23	[campo] FALTAN DATOS PARA VALIDAR INFORMACION	—
24	[campo] VALOR EN CAMPO NO APLICA	—
25	[campo] VALORES REPETIDOS	—
26	[campo] NO SE PERMITEN VALORES DIFERENTES	—
27	[campo] DATO NO COINCIDE CON DTE	—
28	[campo] DTE ESTA RELACIONADO CON OTRO DTE	—
29	[campo] NIT DE CONTRIBUYENTE NO ES VALIDO	—
30	[campo] NIT FUSION NO ES VALIDO	—
31	[campo] NIT DE CONTRIBUYENTE NO AUTORIZADO	El NIT no está autorizado como emisor en ese ambiente.
32	[campo] DIFIERE DE LA FECHA DE ENVIO	—
33	[campo] DOCUMENTO SIN SELLO	El documento que intentas afectar (con una nota o un evento) todavía no tiene sello.
34	[campo] EXCEDE HOLGURA DE 30 MINUTOS	La fecha y hora de emisión difiere más de 30 minutos del envío; casi siempre es hora UTC en lugar de la hora de El Salvador.
94	PARAMETROS NO SON VALIDOS	—
95	CONTRIBUYENTE NO AUTORIZADO PARA EMITIR TIPO DE DTE	El emisor no tiene autorizado ese tipo de DTE; hay que solicitar la ampliación ante el MH.
96	DOCUMENTO NO CUMPLE CON NORMATIVA DE CUMPLIMIENTO	El documento incumple alguna regla de validación de la Normativa; lee las observaciones.
97	NO SE HA PROPORCIONADO DATOS PARA VALIDAR	—
98	DATOS NO CUMPLEN ESTANDAR JSON	—
99	ERROR NO CATALOGADO	—
100	ERROR USUARIO INCORRECTO	—
101	ERROR CONTACTAR CON SOPORTE TÉCNICO	—
102	ERROR NO SE PUDO AUTENTICAR EL USUARIO	—
103	CONTRASEÑA EXPIRADA	—
104	ERROR EN ACTUALIZACIÓN DE CONTRASEÑA	—
105	LA NUEVA CONTRASEÑA Y LA CONFIRMACIÓN DEBE SER LA MISMA	—
106	CREDENCIALES INVÁLIDAS	—
107	ERROR TOKEN INVÁLIDO	—
108	ERROR TOKEN ES REQUERIDO	—
109	ERROR EN GENERACION DE TOKEN	—
110	ERROR EN TIPO REQUERIDO	—
111	ERROR EN PARÁMETRO SOLICITADO	—
112	CODIGO DE GENERACION REEMPLAZO, NO EXISTE	—
113	Número de documento es solicitado para invalidar	—
114	Tipo de documento es solicitado para invalidar	—
115	ERROR NO SE PERMITEN TRIBUTOS DE USO INFORMATIVO	—
116	Fecha menor a 01-01-2000	—