Errores

Cuando una peticion no se puede procesar, la API responde con un JSON como este:

{ "codigo": "301", "mensaje": "Solicitud invalida.", "errores": ["Idempotency-Key: obligatoria."] }

• codigo: codigo del catalogo (ver abajo).
• mensaje: descripcion breve del codigo.
• errores: lista de mensajes. Aparece solo en errores de validacion; en el resto se omite.

Cada respuesta incluye la cabecera X-Correlation-Id. Guardala: ayuda a soporte a rastrear el caso.

Catalogo de codigos#

Codigo	HTTP	Significado	Que hacer	Guia
001	500	Error interno	Reintenta; si persiste, reporta el X-Correlation-Id	Soporte
002	503	Servicio temporalmente no disponible	Reintenta con espera	Reintentos
003	502	El SRI reporto un error	Reintenta; si persiste, reporta	Seguimiento
004	504	El SRI no respondio a tiempo	Reintenta	Seguimiento
005	501	Funcionalidad no implementada	No reintentar; consulta el estado de la operacion	Seguimiento
101	401	API Key invalida o no autorizada para la IP	Revisa la API Key y la IP registrada	Autenticacion
102	403	Origen de la solicitud no autorizado	Revisa la IP registrada	Autenticacion
103	403	Contribuyente, tipo o plan no habilitados	Habilita el contribuyente o el servicio	Ambientes
104	429	Limite de solicitudes excedido	Espera el tiempo de Retry-After y reintenta	Limite de request
200	200 / 202	Operacion exitosa	Continua con el seguimiento	Seguimiento
201	202	Reintento idempotente: misma intencion, mismo resultado	Continua con el seguimiento	Buenas practicas
301	400	Solicitud invalida (formato, cabeceras o campos)	Revisa errores y corrige la solicitud	Primeros pasos
302	422	Comprobante invalido (regla fiscal o estructura)	Revisa errores y corrige el comprobante	Emision
303	400	Filtros invalidos en una consulta	Revisa los filtros	Comprobantes emitidos
305	413	El cuerpo excede el limite (2 MiB en emision)	Reduce el tamano del comprobante	Limites
306	400	Version de API no admitida	Envia X-Api-Version con la version vigente (u omitela)	Versionado
401	409	Comprobante duplicado	No reenvies; consulta la operacion existente	Buenas practicas
403	409	Conflicto de idempotencia o de referencia	Usa la misma Idempotency-Key y el mismo contenido	Buenas practicas
501	429	Cupo agotado	Consulta tu cupo o amplialo	Consumo y cuotas
502	404	Recurso no encontrado	Revisa el identificador	Seguimiento
503	409	Conciliacion requerida	Consulta el estado antes de reenviar	Seguimiento

Como interpretar un error#

• 4xx (400-499): la solicitud tiene un problema. Corrigela antes de reintentar. Reintentar igual no cambia el resultado.
• 5xx (500-599): la plataforma o una dependencia fallo. Reintenta con la misma Idempotency-Key.
• 409 (duplicado / conflicto): no es un fallo de red. Consulta la operacion existente antes de volver a enviar.

Como pedir soporte#

Abre el ticket con estos cinco datos; con ellos se ubica el caso sin mas ida y vuelta:

• La identificacion del emisor.
• La URL completa de la peticion (la URL indica el ambiente).
• El X-Correlation-Id de la respuesta.
• El codigo y el mensaje del error.
• El cuerpo que enviaste, sin la API Key.

No se requieren capturas. El X-Correlation-Id alcanza para encontrar el log.

Siguientes pasos#

• Limites
• Primeros pasos
• Emision