Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
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-Id de 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 el X-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, el msgError y los errores recibidos.
  • El idOperacion, si la emisión llegó a responder 202, y el codEstado de 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#

No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.