En esta página
Errores
Cada respuesta de la API trae un codEstado numérico que te dice qué pasó y si debes esperar, reintentar o corregir; aquí está el catálogo completo.
Cuando una petición falla, la API responde con un estado HTTP y un cuerpo JSON
que trae el estado, un codEstado de cuatro dígitos, como 3002 o 4004, un
msgError con la descripción general del código y la lista errores con el
detalle. El codEstado es estable, así que puedes programar tus decisiones con
él: reintentar después de esperar, corregir el comprobante o avisar a una
persona. El mismo número aparece en el seguimiento de una operación y en los webhooks, de modo que un solo catálogo
te sirve para todo.
Aquí encuentras la forma del error, cómo leer un código por su primer dígito,
el catálogo completo de codEstado con qué hacer ante cada uno, los códigos de
resultado de una operación que no terminó autorizada, los errores que puede
devolver cada tipo de petición y un ejemplo de cómo manejarlos en tu código. Al
final encontrarás qué datos incluir cuando pidas soporte.
Forma del error#
Todos los endpoints responden sus errores con un estado HTTP 4xx o 5xx y un JSON plano como este:
{
"estado": "rechazado",
"codEstado": 3003,
"msgError": "La solicitud no es válida.",
"errores": [
"Idempotency-Key: La cabecera Idempotency-Key es obligatoria y debe ser ASCII estable (maximo 128 caracteres)."
]
}
| Campo | Tipo | Descripción |
|---|---|---|
estado |
string | Estado del resultado. Lo fija el primer dígito de codEstado: en un error HTTP es rechazado, rechazo_configuracion o error. |
codEstado |
integer | Código estable del catálogo, de cuatro dígitos. Programa tus decisiones con este número. |
msgError |
string | Descripción general y fija del código, igual para todas las respuestas con ese codEstado. Puedes mostrarla a un operador, pero no la compares en tu código. Se omite cuando no hay error. |
errores |
array de string | Detalle específico del caso. Viene siempre y es una lista vacía cuando no hay detalle. En 3002 (comprobante_invalido) trae hasta 20 elementos, uno por problema; cuando el problema es de un campo concreto, el texto suele empezar con su ruta, por ejemplo $.infoTributaria.estab: Solo se admiten digitos., y algunas rutas aparecen con nombres en inglés, como items.code. En 3003 (solicitud_invalida) trae el detalle de los parámetros inválidos; puede ser más de uno. En un rechazo del SRI trae el mensaje del SRI. El texto es informativo y puede cambiar, así que muéstralo o regístralo, pero no lo compares en tu código. |
Cada endpoint de emisión por tipo, por ejemplo
POST /v1/contribuyentes/{identificacion}/facturas, responde sus rechazos con
la misma forma que su respuesta 202 y que el
seguimiento de una operación, para que puedas
leer las tres con el mismo código. En un rechazo, idOperacion, urlEstado,
numeroDocumento, claveAcceso, fhRecibido y fhAutorizacion llegan en
null, mientras que ambiente, tipoDocumento y referenciaExterna traen su
valor cuando la API pudo leerlo de tu solicitud:
{
"estado": "rechazado",
"codEstado": 3002,
"msgError": "El comprobante no cumple las validaciones.",
"errores": [
"$.infoTributaria.estab: Solo se admiten digitos."
],
"idOperacion": null,
"urlEstado": null,
"ambiente": 1,
"tipoDocumento": "01",
"numeroDocumento": null,
"referenciaExterna": "FAC-ERP-4581",
"claveAcceso": null,
"fhRecibido": null,
"fhAutorizacion": null
}
Toda respuesta, con error o sin él, trae la cabecera X-Correlation-Id, con la
que podemos ubicar esa petición cuando nos escribes. Te recomendamos guardarla
junto con el error, porque es lo primero que te pedimos en soporte.
Nota
Decide siempre con la pareja de estado HTTP y codEstado. Un mismo código
puede llegar con dos estados HTTP distintos según el endpoint.
Cómo leer un error#
El codEstado tiene cuatro dígitos, y el primero te dice el estado sin
necesidad de buscar el código en el catálogo. Así puedes escribir una regla
general por familia y afinar solo los códigos que necesitan un trato especial.
El estado y el primer dígito#
| Primer dígito | estado |
Qué significa | Acción general |
|---|---|---|---|
| 1 | recibido |
La API recibió el comprobante y todavía no hay un resultado final. | Espera el resultado en el seguimiento o en un webhook. |
| 2 | autorizado |
El SRI autorizó el comprobante; es el único resultado con validez fiscal. | Guarda la claveAcceso y entrega el comprobante. |
| 3 | rechazado |
La solicitud o el comprobante tienen un problema, o el SRI rechazó el comprobante. | Lee errores, corrige y vuelve a enviar. No reintentes la misma petición sin cambios. |
| 4 | rechazo_configuracion |
Falta configuración del emisor o de tu cuenta: firma o cupo. | Corrige la configuración en el Portal del Cliente y después vuelve a emitir. |
| 5 | error |
Tuvimos una falla nuestra o de un servicio del que dependemos, o superaste el límite de solicitudes. | Reintenta con espera; en una emisión, con la misma Idempotency-Key. Las excepciones están en el catálogo. |
| 6 | cancelado |
La plataforma canceló el envío antes de emitir el comprobante. | Emite de nuevo con claves nuevas. |
Como regla práctica, un 4xx no se arregla reintentando la misma petición, salvo el 429 por límite de solicitudes después de esperar. Un 5xx o un corte de red, en cambio, sí se reintentan.
Los dos 429#
El estado HTTP 429 llega con dos códigos que piden acciones opuestas, así que
siempre debes mirar el codEstado antes de decidir. Con 5005
(limite_solicitudes) superaste las solicitudes por minuto: espera los segundos
que indica la cabecera Retry-After y repite la misma petición. Con 4004
(cupo_agotado) no te quedan documentos en paquetes vigentes: esperar no lo
repone, así que no reintentes y compra un paquete, como se explica en Consumo.
Catálogo de codEstado#
Esta es la lista completa de códigos. El nombre de cada código no viaja en el JSON, donde solo llega el número, pero te sirve para leer la documentación y coincide con las constantes de nuestros SDK. La columna HTTP indica el estado HTTP con el que llega el código en una respuesta sincrónica; «seguimiento» significa que lo ves en el seguimiento y en los webhooks, no como un error HTTP.
La columna ¿Reintentar? indica si puedes repetir la misma petición sin
cambiarla. «Con la misma Idempotency-Key» significa que, en una emisión, repites
el mismo cuerpo con la misma cabecera Idempotency-Key para no duplicar el
comprobante; en una consulta GET, basta con repetirla. Si recibes un código
que no está en esta lista, trátalo según su primer dígito y avisa a una persona.
Recibido y autorizado#
Estos códigos no son errores: no traen msgError y su errores llega vacío.
| codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? |
|---|---|---|---|---|---|---|---|
| 1001 | comprobante_recibido |
recibido |
202 / seguimiento | Se omite. | La API recibió la emisión y el comprobante todavía no tiene clave de acceso; claveAcceso llega en null. |
Guarda el idOperacion y espera el resultado en el seguimiento o en un webhook. |
No hace falta |
| 1002 | comprobante_enviado |
recibido |
202 / seguimiento | Se omite. | El comprobante ya tiene su clave de acceso, que llega en claveAcceso, y espera la respuesta del SRI. |
Guarda la claveAcceso y sigue esperando el resultado final. |
No hace falta |
| 2001 | comprobante_autorizado |
autorizado |
Seguimiento | Se omite. | El SRI autorizó el comprobante. fhAutorizacion trae la fecha de autorización. |
Guarda la claveAcceso, descarga el RIDE o el XML y entrega el comprobante. |
No hace falta |
La respuesta 202 de la emisión trae estado en recibido con 1001 o 1002, o
autorizado con 2001 si la autorización ya se conoce. Acepta los tres códigos en
tu integración, guarda la claveAcceso solo cuando no llegue en null y procesa
el cuerpo del 202 con la misma lógica que usas para el seguimiento, porque las dos
respuestas tienen la misma forma. Un rechazo definitivo que la emisión ya conoce
responde 422, no 202.
Rechazado#
| codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? |
|---|---|---|---|---|---|---|---|
| 3001 | rechazo_sri |
rechazado |
422 / seguimiento | El SRI rechazó el comprobante. | El SRI rechazó el comprobante. errores trae el mensaje del SRI. El cupo se consume. Si la emisión directa ya conoce el rechazo, responde 422 con idOperacion y urlEstado; ese 422 consume cupo. |
Corrige el comprobante según errores y emítelo como un comprobante nuevo, con un secuencial nuevo, u omitiéndolo, y claves nuevas. |
No; emite uno nuevo |
| 3002 | comprobante_invalido |
rechazado |
422 / seguimiento | El comprobante no cumple las validaciones. | La Estructura del comprobante no cumple una regla: falta un campo obligatorio, un formato es incorrecto, los totales o impuestos no cuadran, hay campos de otro tipo dentro de info, hay campos desconocidos o repetidos, infoTributaria.ruc es distinto de la identificación de la ruta, o enviaste version, formato, ambiente, tipoEmision o infoTributaria.tipoDocumento, que no se admite porque la ruta fija el tipo. En XML también ocurre si la raíz o infoTributaria.codDoc no corresponden a la ruta, o si la retención usa el XML 1.0 sin docsSustento. En el seguimiento, la validación fiscal rechazó el contenido antes de enviarlo al SRI. |
Lee errores, que trae la ruta del campo, corrige el comprobante y vuelve a enviarlo. Un 422 de validación consume 1 documento como intento; repetir la misma Idempotency-Key con el mismo cuerpo no consume otro. |
No |
| 3003 | solicitud_invalida |
rechazado |
400, 405, 415 | La solicitud no es válida. | El cuerpo no es JSON ni XML válido; falta Idempotency-Key o tiene caracteres no permitidos o más de 128; un parámetro de ruta o de consulta tiene un tipo inválido; usaste un método HTTP que la ruta no admite; el Content-Type no es application/json, application/xml ni text/xml; o, al crear un destino de webhooks en pruebas, ya tienes 10 sin deshabilitar. |
Lee errores, corrige y vuelve a enviar. |
No |
| 3004 | comprobante_duplicado |
rechazado |
409 | Ya existe un comprobante con ese número. | Ya existe un comprobante con el mismo contribuyente, tipo, establecimiento, punto de emisión y secuencial, y está recibido, autorizado o rechazado por el SRI. El número solo se puede reutilizar cuando la operación anterior no llegó a emitir el comprobante, como se explica en Seguimiento de una operación. |
No lo reenvíes. Busca el comprobante existente en el seguimiento. Si querías otro comprobante, usa otro secuencial u omítelo para que se asigne el siguiente. | No |
| 3005 | conflicto_idempotencia |
rechazado |
409 | La Idempotency-Key ya se usó con otro contenido. | Reutilizaste una Idempotency-Key, o una referenciaExterna con el mismo origenReferencia, con un cuerpo distinto al original; o la referenciaExterna ya pertenece a otro comprobante del mismo contribuyente. |
Si es un reintento, reenvía exactamente el cuerpo original. Si es otra emisión, usa una Idempotency-Key y una referenciaExterna nuevas, como se explica en Buenas prácticas. |
No |
| 3006 | cuerpo_excedido |
rechazado |
413 | El cuerpo supera el tamaño permitido. | El cuerpo supera 2 MiB en la emisión o 1 MiB en otros POST y PUT. |
Reduce el tamaño del cuerpo, como se explica en Límites. | No |
| 3007 | version_no_soportada |
rechazado |
400 | Versión de API no admitida. | Enviaste X-Api-Version con un valor no admitido. |
Envía 2026-11-16 o no envíes la cabecera; el detalle está en Versionado. |
No |
| 3008 | no_implementado |
rechazado |
501 | Formato no admitido. | Reservado. La API no devuelve este código actualmente. | Si lo recibes, envía el comprobante en JSON o en el XML del SRI y escribe a soporte con el X-Correlation-Id. |
No |
| 3009 | credenciales_invalidas |
rechazado |
401 | Credenciales inválidas. | Falta X-Api-Key, la API Key está mal formada, no existe, está revocada, venció o pertenece a otro ambiente. |
Revisa la cabecera y la API Key, como se explica en Autenticación. | No |
| 3010 | ip_no_autorizada |
rechazado |
403 | IP no autorizada. | En producción, la API Key es válida, pero la IP de origen no está registrada para tu integración, o la API no pudo identificar la IP de la conexión. El sandbox no exige IP registrada. | Registra tu IP pública de producción en Cuenta > IP permitidas o llama directo a la URL de la API, como se explica en Autenticación. | No |
| 3011 | acceso_denegado |
rechazado |
403 | Contribuyente, tipo o suscripción no habilitados. | El contribuyente de la ruta o el tipo de comprobante no están habilitados para tu integración. | Revisa GET /v1/contexto, como se explica en Ambientes. |
No |
| 3012 | filtros_invalidos |
rechazado |
400 | Filtros inválidos. | Un filtro de una consulta está fuera de rango: fechas o max. |
Ajusta los filtros a los límites. | No |
| 3013 | no_encontrado |
rechazado |
404 | Recurso no encontrado. | El idOperacion, la clave de acceso o el RIDE no existen, no pertenecen a tu integración o aún no están disponibles; o tu integración no tiene paquetes en este ambiente (GET /v1/consumo). Un contribuyente de marca blanca, con marcaBlanca en true en /v1/contexto, no tiene RIDE y recibe siempre este código al pedirlo. |
Revisa el identificador y la URL del ambiente. Si es un RIDE recién autorizado, reintenta más tarde. Si el contribuyente es de marca blanca, descarga el XML. | No; un RIDE recién autorizado, sí, más tarde, salvo en marca blanca |
| 3014 | correo_no_disponible |
rechazado |
409 | Correo no disponible para el emisor. | Reservado. El reenvío de correo no está disponible. | Descarga el XML y envía el comprobante desde tu sistema. | No |
Rechazo de configuración#
| codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? |
|---|---|---|---|---|---|---|---|
| 4001 | emisor_no_configurado |
rechazo_configuracion |
422 / seguimiento | Al emisor le falta configuración. | Al emisor le falta configuración para emitir ante el SRI. | Revisa el RUC en Cuenta > Contribuyentes del Portal del Cliente: en el ambiente en que emitiste, la columna Pruebas o Producción debe mostrar Listo o En producción. Si muestra Configurando, espera a que termine; si ya está listo, escribe a soporte con el idOperacion. Después reenvía con claves nuevas. |
No; reenvía después de corregir |
| 4002 | firma_no_valida |
rechazo_configuracion |
422 / seguimiento | La firma electrónica no es válida. | La firma electrónica del emisor está caducada o no es válida. | En Cuenta > Contribuyentes del Portal del Cliente, pulsa Reemplazar firma en la fila del RUC y carga una firma electrónica vigente; si tu portal no muestra esa opción, cárgala en Cuenta > Certificados con Reemplazar certificado. Después reenvía con claves nuevas. | No; reenvía después de corregir |
| 4003 | suscripcion_inactiva |
rechazo_configuracion |
422 / seguimiento | La suscripción no está activa. | El servicio de emisión de tu cuenta no está activo en este ambiente. | Escribe a soporte para reactivarlo y reenvía con claves nuevas. | No; reenvía después de corregir |
| 4004 | cupo_agotado |
rechazo_configuracion |
429 / seguimiento | Cupo agotado. | No te quedan documentos en tus paquetes vigentes. | Consulta GET /v1/consumo y compra un paquete. Esperar lo que indica Retry-After no lo repone. |
No, hasta ampliar el cupo |
Error#
| codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? |
|---|---|---|---|---|---|---|---|
| 5001 | error_interno |
error |
500 / seguimiento | Error interno. | Tuvimos un fallo no previsto. En el seguimiento, el comprobante no se completó. | En una respuesta 500, reintenta con espera exponencial y, si persiste, reporta el X-Correlation-Id a soporte. En el seguimiento, escribe a soporte con el idOperacion antes de reemitir. |
500: con la misma Idempotency-Key. Seguimiento: no, hasta que soporte lo confirme |
| 5002 | servicio_no_disponible |
error |
503 | Servicio temporalmente no disponible. | Nuestro servicio no está disponible por un momento. | Espera los segundos que indica Retry-After y reintenta. |
Con la misma Idempotency-Key |
| 5003 | error_dependencia |
error |
502 | Un servicio externo reportó un error. | Un servicio externo devolvió un error en una llamada sincrónica: consultas al SRI, el seguimiento, descarga del RIDE o del XML, o perfil del emisor. | Reintenta con espera. Si persiste, reporta el X-Correlation-Id. |
Sí |
| 5004 | tiempo_agotado |
error |
504 | Un servicio externo no respondió a tiempo. | Un servicio externo no respondió a tiempo en una consulta sincrónica: consultas al SRI, el seguimiento, descarga del RIDE o del XML, o perfil del emisor. | Reintenta con espera. | Sí |
| 5005 | limite_solicitudes |
error |
429 | Límite de solicitudes excedido. | Superaste las solicitudes por minuto de tu integración, tu IP acumuló 20 autenticaciones fallidas en el minuto, o el servicio externo de una consulta al SRI limitó las solicitudes. | Espera los segundos que indica Retry-After; el detalle está en Límite de request. |
Con la misma Idempotency-Key, después de Retry-After |
| 5006 | entrega_no_posible |
error |
Seguimiento | El comprobante no se pudo emitir. | El comprobante no se pudo emitir y confirmamos que no se creó. | Reenvía con claves nuevas. | Sí, con claves nuevas |
| 5007 | resultado_no_confirmado |
error |
Seguimiento | No se pudo confirmar el resultado. | No pudimos confirmar si el comprobante llegó a crearse. | No reemitas, porque podrías duplicarlo. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
No, hasta que soporte lo confirme |
Cancelado#
| codEstado | Nombre | estado | HTTP | msgError | Cuándo ocurre | Qué hacer | ¿Reintentar? |
|---|---|---|---|---|---|---|---|
| 6001 | operacion_cancelada |
cancelado |
Seguimiento | La plataforma canceló el envío. | La plataforma canceló el envío antes de emitir el comprobante. No consumió cupo y no genera webhook. | Emite de nuevo con claves nuevas. | Sí, con claves nuevas |
Códigos de resultado de una operación#
Una emisión que respondió 202 no termina con un error HTTP, aunque no llegue a
autorizarse. El resultado lo ves en el estado del
seguimiento y en el cuerpo de los
webhooks. Cuando ese estado es final y distinto de
autorizado, el campo codEstado trae uno de estos códigos, msgError su
descripción general y errores el detalle del caso, por ejemplo el mensaje del
SRI en un 3001.
En la tabla, «claves nuevas» significa una Idempotency-Key nueva y una
referenciaExterna nueva, y «el mismo número» significa el mismo estab,
ptoEmi y secuencial del comprobante anterior.
| codEstado | Nombre | Estado | Qué hacer | Reenviar |
|---|---|---|---|---|
| 3001 | rechazo_sri |
rechazado |
Corrige el comprobante según el mensaje del SRI que trae errores y emítelo como un comprobante nuevo, con un secuencial nuevo, u omitiéndolo, y claves nuevas. |
Sí, con otro número |
| 3002 | comprobante_invalido |
rechazado |
Corrige el dato que indica errores y reenvía con claves nuevas. |
Sí, con el mismo número |
| 4001 | emisor_no_configurado |
rechazo_configuracion |
Completa la configuración del emisor en el Portal del Cliente y reenvía con claves nuevas. | Sí, con el mismo número |
| 4002 | firma_no_valida |
rechazo_configuracion |
Carga una firma electrónica vigente y reenvía con claves nuevas. | Sí, con el mismo número |
| 4003 | suscripcion_inactiva |
rechazo_configuracion |
Escribe a soporte para reactivar el servicio de emisión y reenvía con claves nuevas. | Sí, con el mismo número |
| 4004 | cupo_agotado |
rechazo_configuracion |
Compra un paquete de documentos y reenvía con claves nuevas. | Sí, con el mismo número |
| 5006 | entrega_no_posible |
error |
Reenvía con claves nuevas. | Sí, con el mismo número |
| 5007 | resultado_no_confirmado |
error |
No reemitas, porque podrías duplicarlo. Búscalo en el seguimiento y escribe a soporte con el idOperacion. |
No, hasta que soporte lo confirme |
| 5001 | error_interno |
error |
Escribe a soporte con el idOperacion antes de reemitir. |
No, hasta que soporte lo confirme |
| 6001 | operacion_cancelada |
cancelado |
Emite de nuevo con claves nuevas. | Sí, con el mismo número |
Cada comprobante que el SRI autoriza o rechaza consume un documento de tu
cupo; uno cancelado no lo consume, y al reenviarlo con claves nuevas se
cuenta el nuevo envío. Si recibes un código que no está en esta tabla, trátalo
como un rechazo que debe revisar una persona.
Respuestas de error de /v1#
Todas las respuestas de error de /v1 traen el mismo sobre con estado,
codEstado, msgError y errores, y las cabeceras X-Correlation-Id y
X-Api-Version, aunque la petición no haya llegado a un endpoint. La emisión es
la excepción: sus rechazos traen la misma forma que su respuesta 202, con la
información de la operación.
| HTTP | codEstado | Cuándo ocurre | Qué hacer |
|---|---|---|---|
| 404 | 3013 | La ruta no existe: hay un error de escritura, falta /v1 o un {idOperacion} no es un UUID. |
Revisa la ruta contra la guía del endpoint. |
| 405 | 3003 | Usaste un método HTTP que la ruta no admite, por ejemplo GET en la emisión. |
Usa el método documentado. |
| 415 | 3003 | Enviaste un cuerpo sin Content-Type: application/json, application/xml o text/xml, por ejemplo con text/plain o sin la cabecera. |
Agrega el Content-Type que corresponda al cuerpo. |
Errores por situación#
Al autenticar#
Estas son las causas por las que una ruta /v1 rechaza la autenticación. Si
coinciden varias, la respuesta informa de una sola.
| codEstado | HTTP | Causa | Qué hacer |
|---|---|---|---|
3007 (version_no_soportada) |
400 | X-Api-Version inválida. |
Envía 2026-11-16 o no envíes la cabecera. |
3009 (credenciales_invalidas) |
401 | La API Key falta, no existe, está revocada, venció o es de otro ambiente. | Revisa la cabecera y la API Key. |
3010 (ip_no_autorizada) |
403 | En producción, la API Key es válida, pero la IP no está permitida o no se pudo identificar. | Registra tu IP pública de producción. El sandbox no exige IP registrada. |
5005 (limite_solicitudes) |
429 | Tu IP acumuló 20 autenticaciones fallidas en el minuto, o superaste las solicitudes por minuto de tu integración. | Espera los segundos que indica Retry-After. |
Al emitir#
En cada endpoint de emisión por tipo, como
POST /v1/contribuyentes/{identificacion}/facturas, la API responde con uno de
estos resultados. Si coinciden varias causas, la respuesta informa de una sola;
corrige y vuelve a enviar hasta recibir el 202. La ruta fija el tipo de
comprobante: elige la ruta del tipo que emites y no envíes
infoTributaria.tipoDocumento en el cuerpo, ni siquiera con el valor de la
ruta, porque la API responde 422 con 3002 y lo señala como campo no soportado.
Todas estas respuestas tienen la forma de la emisión que se describe en
Forma del error:
| codEstado | HTTP | Causa | Consume cupo |
|---|---|---|---|
| 3006 | 413 | El cuerpo supera 2 MiB. | No |
| 3003 | 415 | El Content-Type no es JSON ni XML. |
No |
| 3003 | 400 | El JSON o el XML está mal formado, o la Idempotency-Key falta o es inválida. |
No |
| 3002 | 422 | La estructura, un formato o una regla fiscal del comprobante no se cumplen, o el cuerpo trae un campo que la ruta no admite, como infoTributaria.tipoDocumento. |
Sí, 1 documento como intento |
| 3011 | 403 | El contribuyente, el tipo de comprobante o el servicio no están habilitados, o infoTributaria.ruc no corresponde al contribuyente. |
No |
| 3005 | 409 | Usaste la misma Idempotency-Key o referenciaExterna con otro cuerpo. |
No |
| 3004 | 409 | El número ya está registrado en un comprobante recibido, autorizado o rechazado por el SRI. |
No |
| 4004 | 429 | El cupo está agotado. | No |
| 1001 o 1002 | 202 | La API recibió la emisión, o es un reintento idempotente de una emisión ya recibida. El cuerpo trae estado en recibido, el idOperacion y la urlEstado, que también llega en la cabecera Location. |
Se consume cuando el SRI autoriza o rechaza el comprobante; un reintento idempotente no consume otro documento |
| 3001, 4001, 4002 o 4003 | 422 | La emisión directa ya conoce un rechazo definitivo (rechazado o rechazo_configuracion). El cuerpo trae el codEstado, el msgError, el detalle en errores, el idOperacion y la urlEstado. |
Depende del caso: consulta Consumo y cuotas |
| 5002 o 5001 | 503 o 500 | Tuvimos una falla temporal. Reintenta con la misma Idempotency-Key. |
No |
Un 202 significa que la solicitud fue recibida, no que el SRI la autorizó.
Si el comprobante no llega a autorizarse, el resultado llega después en el
seguimiento o en un webhook, con el estado
final y uno de los códigos de resultado;
no es un error HTTP. El recorrido completo está en
Ciclo de vida del comprobante.
Al consultar#
| Endpoint | codEstado | HTTP | Causa |
|---|---|---|---|
GET /v1/operaciones/{idOperacion} |
3013 | 404 | La operación no existe o es de otra integración o de otro ambiente. |
GET /v1/consumo |
3013 | 404 | Tu integración no tiene paquetes en este ambiente. |
GET /v1/operaciones |
3003 o 3012 | 400 | Falta identificacion o un filtro está fuera de rango, como se explica en Límites. |
GET /v1/catalogos/{nombre} |
3013 | 404 | No existe un catálogo con esa clave. |
GET /v1/catalogos y GET /v1/catalogos/{nombre} |
5002 | 503 | Los catálogos no están disponibles por un momento. Reintenta con espera. |
GET /estado |
5005 | 429 | Tu IP superó las 60 consultas por minuto. |
GET /v1/consultas/... |
3003 o 3012 | 400 | Falta un dato obligatorio o un filtro está fuera de rango. |
GET /v1/consultas/... |
3013 | 404 | El SRI no tiene datos para esa consulta. |
GET /v1/consultas/... |
5003, 5004 o 5005 | 502, 504 o 429 | El servicio de consulta falló, no respondió o limitó las solicitudes. |
Al descargar archivos#
| Endpoint | codEstado | HTTP | Causa |
|---|---|---|---|
GET .../comprobantes/{claveAcceso}/ride y .../xml |
3003 | 400 | La clave de acceso no tiene un formato válido de 49 dígitos. |
GET .../comprobantes/{claveAcceso}/ride |
3013 | 404 | El comprobante no existe para ese contribuyente, el RIDE aún no está disponible o el contribuyente es de marca blanca y no tiene RIDE. |
GET .../comprobantes/{claveAcceso}/ride y .../xml |
5004 | 504 | Nuestro servicio que entrega el archivo no respondió a tiempo. Reintenta con espera. |
GET .../comprobantes/{claveAcceso}/ride y .../xml |
5003 | 502 | Nuestro servicio que entrega el archivo devolvió un error. Reintenta con espera. |
GET .../comprobantes/{claveAcceso}/xml |
3013 | 404 | El comprobante no existe para ese contribuyente. |
Por ejemplo, el RIDE de un contribuyente de marca blanca responde así:
{
"estado": "rechazado",
"codEstado": 3013,
"msgError": "Recurso no encontrado.",
"errores": []
}
Al gestionar el perfil del emisor#
| Endpoint | codEstado | HTTP | Causa |
|---|---|---|---|
GET y PUT .../perfil, POST .../perfil/logo |
3011 | 403 | El contribuyente no está habilitado para tu integración. |
PUT .../perfil |
3003 | 400 | El JSON está mal formado o incluye un campo que no es editable. |
POST .../perfil/logo |
3003 | 400 | Falta el archivo, está vacío, supera 512 KB o no es PNG ni JPEG. |
PUT .../perfil y POST .../perfil/logo |
3006 | 413 | El cuerpo supera 1 MiB. |
GET y PUT .../perfil, POST .../perfil/logo |
5003 o 5004 | 502 o 504 | El servicio del perfil devolvió un error o no respondió a tiempo. |
El detalle y los ejemplos están en Perfil del emisor.
Maneja los errores en tu código#
El ejemplo envía una factura al endpoint de su tipo y decide qué hacer según el
estado HTTP y el codEstado, leyendo también msgError, errores y la
cabecera X-Correlation-Id. Ante el 202 acepta los dos códigos de recibido,
1001 y 1002, y guarda la claveAcceso solo si no llega en null. Para
ejecutarlo, guarda el JSON de Factura como
comprobante.json; el cuerpo no lleva infoTributaria.tipoDocumento, porque
la ruta fija el tipo.
Importante
Ambiente de pruebas: sin validez fiscal.
# -i muestra las cabeceras: busca X-Correlation-Id y, en un 429, Retry-After.
# El cuerpo trae estado, codEstado, msgError (solo si hay error) y errores.
curl -s -i -X POST \
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas" \
-H "X-Api-Key: $ECUAFACT_API_KEY" \
-H "Idempotency-Key: FACTURA-2026-0001" \
-H "Content-Type: application/json" \
-d @comprobante.json
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Text.Json;
string apiKey = Environment.GetEnvironmentVariable("ECUAFACT_API_KEY")!;
using var http = new HttpClient { BaseAddress = new Uri("https://api-sandbox.mynexusapi.com") };
http.DefaultRequestHeaders.Add("X-Api-Key", apiKey);
using var peticion = new HttpRequestMessage(HttpMethod.Post, "/v1/contribuyentes/0123456789001/facturas");
peticion.Headers.Add("Idempotency-Key", "FACTURA-2026-0001");
peticion.Content = new StringContent(
await File.ReadAllTextAsync("comprobante.json"), Encoding.UTF8, "application/json");
using HttpResponseMessage respuesta = await http.SendAsync(peticion);
int estado = (int)respuesta.StatusCode;
string correlacion = respuesta.Headers.TryGetValues("X-Correlation-Id", out IEnumerable<string>? valores)
? valores.First() : "";
string cuerpo = await respuesta.Content.ReadAsStringAsync();
int codEstado = 0;
string msgError = "";
List<string> errores = new();
string? claveAcceso = null;
if (cuerpo.Length > 0)
{
using JsonDocument json = JsonDocument.Parse(cuerpo);
JsonElement raiz = json.RootElement;
codEstado = raiz.TryGetProperty("codEstado", out JsonElement cod) ? cod.GetInt32() : 0;
msgError = raiz.TryGetProperty("msgError", out JsonElement msg) ? msg.GetString() ?? "" : "";
if (raiz.TryGetProperty("errores", out JsonElement lista))
{
foreach (JsonElement item in lista.EnumerateArray())
{
errores.Add(item.GetString() ?? "");
}
}
if (raiz.TryGetProperty("claveAcceso", out JsonElement clave) && clave.ValueKind == JsonValueKind.String)
{
claveAcceso = clave.GetString();
}
}
if (estado == 202)
{
// 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso.
Console.WriteLine($"Recibido ({codEstado}). Clave de acceso: {claveAcceso ?? "pendiente"}");
return;
}
Console.WriteLine($"HTTP {estado} {codEstado}: {msgError} (X-Correlation-Id: {correlacion})");
foreach (string detalle in errores)
{
Console.WriteLine($" - {detalle}");
}
string accion = (estado, codEstado) switch
{
(400, _) or (413, _) or (415, _) or (422, _) => "Corrige la solicitud y vuelve a enviarla.",
(401, _) => "Revisa la API Key y la IP registrada.",
(403, _) => "Revisa el contribuyente y el tipo de comprobante en /v1/contexto.",
(409, 3004) => "El numero ya existe: busca el comprobante existente.",
(409, _) => "Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.",
(429, 4004) => "Cupo agotado: amplialo antes de seguir. No reintentes.",
(429, _) => $"Espera {respuesta.Headers.RetryAfter?.Delta?.TotalSeconds ?? 60} s y reintenta con la misma Idempotency-Key.",
(>= 500, _) => "Reintenta con la misma Idempotency-Key y espera exponencial.",
_ => "Revisa el catalogo de errores."
};
Console.WriteLine(accion);
import json
import os
import requests
with open("comprobante.json", encoding="utf-8") as archivo:
cuerpo = json.load(archivo)
r = requests.post(
"https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas",
headers={
"X-Api-Key": os.environ["ECUAFACT_API_KEY"],
"Idempotency-Key": "FACTURA-2026-0001",
},
json=cuerpo,
timeout=30,
)
correlacion = r.headers.get("X-Correlation-Id", "")
respuesta = r.json() if r.content else {}
cod_estado = respuesta.get("codEstado", 0)
if r.status_code == 202:
# 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso.
print(f"Recibido ({cod_estado}). Clave de acceso:", respuesta.get("claveAcceso") or "pendiente")
else:
msg_error = respuesta.get("msgError", "")
errores = respuesta.get("errores", [])
print(f"HTTP {r.status_code} {cod_estado}: {msg_error} (X-Correlation-Id: {correlacion})")
for detalle in errores:
print(" -", detalle)
if r.status_code in (400, 413, 415, 422):
print("Corrige la solicitud y vuelve a enviarla.")
elif r.status_code == 401:
print("Revisa la API Key y la IP registrada.")
elif r.status_code == 403:
print("Revisa el contribuyente y el tipo de comprobante en /v1/contexto.")
elif r.status_code == 409 and cod_estado == 3004:
print("El numero ya existe: busca el comprobante existente.")
elif r.status_code == 409:
print("Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.")
elif r.status_code == 429 and cod_estado == 4004:
print("Cupo agotado: amplialo antes de seguir. No reintentes.")
elif r.status_code == 429:
print(f"Espera {r.headers.get('Retry-After', '60')} s y reintenta con la misma Idempotency-Key.")
elif r.status_code == 415:
print("Tipo de contenido no admitido: envia JSON o XML.")
elif r.status_code >= 500:
print("Reintenta con la misma Idempotency-Key y espera exponencial.")
// Node.js 18 o superior. Guarda como errores.mjs y ejecuta: node errores.mjs
import { readFile } from 'node:fs/promises';
const res = await fetch(
'https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas',
{
method: 'POST',
headers: {
'X-Api-Key': process.env.ECUAFACT_API_KEY,
'Idempotency-Key': 'FACTURA-2026-0001',
'Content-Type': 'application/json'
},
body: await readFile('comprobante.json', 'utf8')
});
const correlacion = res.headers.get('X-Correlation-Id') ?? '';
const texto = await res.text();
const respuesta = texto ? JSON.parse(texto) : {};
const codEstado = respuesta.codEstado ?? 0;
if (res.status === 202) {
// 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso.
console.log(`Recibido (${codEstado}). Clave de acceso: ${respuesta.claveAcceso ?? 'pendiente'}`);
} else {
console.log(`HTTP ${res.status} ${codEstado}: ${respuesta.msgError ?? ''} (X-Correlation-Id: ${correlacion})`);
for (const detalle of respuesta.errores ?? []) {
console.log(' -', detalle);
}
if ([400, 413, 415, 422].includes(res.status)) {
console.log('Corrige la solicitud y vuelve a enviarla.');
} else if (res.status === 401) {
console.log('Revisa la API Key y la IP registrada.');
} else if (res.status === 403) {
console.log('Revisa el contribuyente y el tipo de comprobante en /v1/contexto.');
} else if (res.status === 409 && codEstado === 3004) {
console.log('El numero ya existe: busca el comprobante existente.');
} else if (res.status === 409) {
console.log('Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.');
} else if (res.status === 429 && codEstado === 4004) {
console.log('Cupo agotado: amplialo antes de seguir. No reintentes.');
} else if (res.status === 429) {
console.log(`Espera ${res.headers.get('Retry-After') ?? '60'} s y reintenta con la misma Idempotency-Key.`);
} else if (res.status === 415) {
console.log('Tipo de contenido no admitido: envia JSON o XML.');
} else if (res.status >= 500) {
console.log('Reintenta con la misma Idempotency-Key y espera exponencial.');
}
}
<?php
$cabecerasRespuesta = [];
$ch = curl_init('https://api-sandbox.mynexusapi.com/v1/contribuyentes/0123456789001/facturas');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'X-Api-Key: ' . getenv('ECUAFACT_API_KEY'),
'Idempotency-Key: FACTURA-2026-0001',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => file_get_contents('comprobante.json'),
CURLOPT_HEADERFUNCTION => function ($ch, $linea) use (&$cabecerasRespuesta) {
$partes = explode(':', $linea, 2);
if (count($partes) === 2) {
$cabecerasRespuesta[strtolower(trim($partes[0]))] = trim($partes[1]);
}
return strlen($linea);
},
]);
$cuerpo = curl_exec($ch);
$estado = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$correlacion = $cabecerasRespuesta['x-correlation-id'] ?? '';
$respuesta = $cuerpo ? json_decode($cuerpo, true) : [];
$codEstado = (int) ($respuesta['codEstado'] ?? 0);
if ($estado === 202) {
// 1001: todavia sin clave de acceso. 1002: ya trae claveAcceso.
echo "Recibido ($codEstado). Clave de acceso: " . ($respuesta['claveAcceso'] ?? 'pendiente') . PHP_EOL;
exit;
}
echo "HTTP $estado $codEstado: " . ($respuesta['msgError'] ?? '') . " (X-Correlation-Id: $correlacion)" . PHP_EOL;
foreach ($respuesta['errores'] ?? [] as $detalle) {
echo ' - ' . $detalle . PHP_EOL;
}
if (in_array($estado, [400, 413, 415, 422], true)) {
echo 'Corrige la solicitud y vuelve a enviarla.' . PHP_EOL;
} elseif ($estado === 401) {
echo 'Revisa la API Key y la IP registrada.' . PHP_EOL;
} elseif ($estado === 403) {
echo 'Revisa el contribuyente y el tipo de comprobante en /v1/contexto.' . PHP_EOL;
} elseif ($estado === 409 && $codEstado === 3004) {
echo 'El numero ya existe: busca el comprobante existente.' . PHP_EOL;
} elseif ($estado === 409) {
echo 'Reenvia el cuerpo original o usa una Idempotency-Key nueva para otra emision.' . PHP_EOL;
} elseif ($estado === 429 && $codEstado === 4004) {
echo 'Cupo agotado: amplialo antes de seguir. No reintentes.' . PHP_EOL;
} elseif ($estado === 429) {
echo 'Espera ' . ($cabecerasRespuesta['retry-after'] ?? '60') . ' s y reintenta con la misma Idempotency-Key.' . PHP_EOL;
} elseif ($estado === 415) {
echo 'Tipo de contenido no admitido: envia JSON o XML.' . PHP_EOL;
} elseif ($estado >= 500) {
echo 'Reintenta con la misma Idempotency-Key y espera exponencial.' . PHP_EOL;
}
using Ecuafact.Sdk;
using Ecuafact.Sdk.Contracts;
// client: cliente EcuafactClient - ver SDK .NET. comprobante: tu Estructura del comprobante.
try
{
EmisionResultado resultado = await client.EmitirAsync("0123456789001", comprobante, "FACTURA-2026-0001");
Console.WriteLine($"Recibido ({resultado.Admission.CodEstado}): {resultado.Admission.IdOperacion}");
}
catch (EcuafactApiException ex)
{
Console.WriteLine($"HTTP {ex.EstadoHttp} {ex.CodEstado}: {ex.MsgError} (X-Correlation-Id: {ex.CorrelationId})");
foreach (string detalle in ex.Errores)
{
Console.WriteLine($" - {detalle}");
}
if (ex.CodEstado == CodEstado.CupoAgotado)
{
Console.WriteLine("Cupo agotado: amplialo antes de seguir. No reintentes.");
}
}
from ecuafact import CodEstado, EcuafactApiException
# client: cliente EcuafactClient - ver SDK Python. comprobante: tu Estructura del comprobante.
try:
resultado = client.emitir_en("0123456789001", comprobante, "FACTURA-2026-0001")
print(f"Recibido ({resultado.admission.cod_estado}):", resultado.admission.id_operacion)
except EcuafactApiException as ex:
print(f"HTTP {ex.estado_http} {ex.cod_estado}: {ex.msg_error} (X-Correlation-Id: {ex.correlation_id})")
for detalle in ex.errores:
print(" -", detalle)
if ex.cod_estado == CodEstado.CUPO_AGOTADO:
print("Cupo agotado: amplialo antes de seguir. No reintentes.")
import { CodEstado, EcuafactApiException } from "@ecuafact/sdk";
// client: cliente EcuafactClient - ver SDK Node.js. comprobante: tu Estructura del comprobante.
try {
const resultado = await client.emitirFacturaEn("0123456789001", comprobante, "FACTURA-2026-0001");
console.log(`Recibido (${resultado.admission.codEstado}):`, resultado.admission.idOperacion);
} catch (ex) {
if (!(ex instanceof EcuafactApiException)) throw ex;
console.log(`HTTP ${ex.estadoHttp} ${ex.codEstado}: ${ex.msgError} (X-Correlation-Id: ${ex.correlationId})`);
for (const detalle of ex.errores) console.log(" -", detalle);
if (ex.codEstado === CodEstado.CupoAgotado) console.log("Cupo agotado: amplialo antes de seguir. No reintentes.");
}
<?php
use Ecuafact\Sdk\Contracts\CodEstado;
use Ecuafact\Sdk\EcuafactApiException;
// $client: cliente EcuafactClient - ver SDK PHP. $comprobante: tu Estructura del comprobante.
try {
$resultado = $client->emitirEn('0123456789001', $comprobante, 'FACTURA-2026-0001');
echo "Recibido ({$resultado->admission->codEstado}): " . $resultado->admission->idOperacion . PHP_EOL;
} catch (EcuafactApiException $ex) {
echo "HTTP {$ex->estadoHttp} {$ex->codEstado}: {$ex->msgError} (X-Correlation-Id: {$ex->correlationId})" . PHP_EOL;
foreach ($ex->errores as $detalle) {
echo ' - ' . $detalle . PHP_EOL;
}
if ($ex->codEstado === CodEstado::CUPO_AGOTADO) {
echo 'Cupo agotado: amplialo antes de seguir. No reintentes.' . PHP_EOL;
}
}
import com.ecuafact.sdk.EcuafactApiException;
import com.ecuafact.sdk.EmisionResultado;
import com.ecuafact.sdk.contracts.CodEstado;
// client: cliente EcuafactClient - ver SDK Java. comprobante: tu Estructura del comprobante.
try {
EmisionResultado resultado = client.emitirEn("0123456789001", comprobante, "FACTURA-2026-0001");
System.out.println("Recibido (" + resultado.admission().codEstado() + "): " + resultado.admission().idOperacion());
} catch (EcuafactApiException ex) {
System.out.println("HTTP " + ex.estadoHttp() + " " + ex.codEstado() + ": " + ex.msgError()
+ " (X-Correlation-Id: " + ex.correlationId() + ")");
ex.errores().forEach(detalle -> System.out.println(" - " + detalle));
if (ex.codEstado() == CodEstado.CUPO_AGOTADO) {
System.out.println("Cupo agotado: amplialo antes de seguir. No reintentes.");
}
}
Si usas nuestros SDK oficiales, no necesitas programar estos reintentos:
reintentan solos, con la misma Idempotency-Key, los cortes de red y los
estados 408, 425, 500, 502, 503 y 504, hasta 3 intentos en total y respetando
Retry-After. Un 429 con el codEstado 5005 también se reintenta por defecto, y
puedes desactivarlo con la opción de reintento por límite del SDK:
RetryRateLimited en .NET, retry_rate_limited en Python y retryRateLimited
en Node.js, PHP y Java. Un 429 con el codEstado 4004 no se reintenta nunca. La
excepción llega cuando se agotan los intentos o cuando el error no se reintenta;
el detalle está en SDKs.
Cómo pedir soporte#
Abre un ticket en soporte.ecuafact.com. También puedes consultar el centro de ayuda, escribir por WhatsApp o usar la página de contacto. Horario: lunes a viernes, 09:00-18:00 GMT-5. Primera respuesta: 1 día hábil; producción caída: 4 horas.
Si necesitas ayuda, incluye estos datos; con ellos podemos ubicar tu caso sin más idas y vueltas:
- El
X-Correlation-Idde la respuesta, que es el dato más importante. - El valor de
X-Additional-Info, si lo enviaste. Podemos buscar tu solicitud por ese texto aunque no tengas elX-Correlation-Id, como se explica en Identifica tus solicitudes. - La fecha y la hora aproximadas de la petición.
- La URL completa de la petición, que indica el ambiente.
- El estado HTTP, el
codEstado, elmsgErrory loserroresrecibidos. - El
idOperacion, si la emisión llegó a responder 202, y elcodEstadode la operación si no terminó autorizada. - El cuerpo que enviaste, sin la API Key.
No hace falta adjuntar capturas de pantalla.
Atención
Nunca incluyas tu API Key ni el secreto de tus webhooks en un ticket, un correo o un chat de soporte. No los necesitamos para ayudarte.
Siguientes pasos#
- Buenas prácticas: reintentos con espera exponencial e idempotencia, con código listo para copiar.
- Límite de request: cómo leer
Retry-Aftery las cabecerasX-RateLimit-*. - Comprobantes electrónicos: las reglas de la Estructura del comprobante que evitan un 422.
- Respuestas del API: forma de las respuestas exitosas y cabeceras comunes.