<!-- source_url: https://docs.mynexusapi.com/v1/guias/errores | last_updated: 2026-11-19 -->

# 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:

```json
{
  "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](#catalogo-de-codestado), 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](/v1/guias/consulta-operacion), 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:

```json
{
  "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.

> [!NOTE]
> 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](/v1/guias/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](/v1/guias/consulta-operacion) y en los
[webhooks](/v1/guias/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](/v1/guias/consulta-ride) o el [XML](/v1/guias/consulta-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](/v1/guias/consulta-operacion#que-hacer-segun-el-estado). | 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](/v1/guias/buenas-practicas#idempotencia). | 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](/v1/guias/limites). | 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](/v1/guias/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](#como-pedir-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](/v1/guias/autenticacion#cuando-aparece-3009). | 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](/v1/guias/autenticacion#cuando-aparece-3010). | 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](/v1/guias/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](/v1/guias/limites). | 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`](/v1/guias/consulta-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](/v1/guias/consulta-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](/v1/guias/consulta-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](#como-pedir-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`](/v1/guias/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](#como-pedir-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](/v1/guias/consulta-contribuyente), el seguimiento, descarga del [RIDE](/v1/guias/consulta-ride) o del [XML](/v1/guias/consulta-xml), o [perfil del emisor](/v1/guias/perfil-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](/v1/guias/consulta-contribuyente), el seguimiento, descarga del RIDE o del XML, o [perfil del emisor](/v1/guias/perfil-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](/v1/guias/limite-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](#como-pedir-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](/v1/guias/consulta-operacion) y en el cuerpo de los
[webhooks](/v1/guias/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](#como-pedir-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](#como-pedir-soporte) con el `idOperacion`. | No, hasta que soporte lo confirme |
| 5001 | `error_interno` | `error` | Escribe a [soporte](#como-pedir-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](#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](/v1/guias/consumo) |
| 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](/v1/guias/consulta-operacion) o en un webhook, con el `estado`
final y uno de los [códigos de resultado](#codigos-de-resultado-de-una-operacion);
no es un error HTTP. El recorrido completo está en
[Ciclo de vida del comprobante](/v1/guias/ciclo-de-vida).

### 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](/v1/guias/limites#consultas). |
| `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í:

```json
{
  "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](/v1/guias/perfil-emisor#estados-de-este-endpoint).

## 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](/v1/guias/emision-01) como
`comprobante.json`; el cuerpo no lleva `infoTributaria.tipoDocumento`, porque
la ruta fija el tipo.

> [!IMPORTANT]
> Ambiente de pruebas: sin validez fiscal.

```bash
# -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
```

```csharp
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);
```

```python
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.")
```

```javascript
// 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
<?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;
}
```

```csharp-sdk
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.");
    }
}
```

```python-sdk
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.")
```

```javascript-sdk
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-sdk
<?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;
    }
}
```

```java-sdk
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](/v1/guias/sdk).

## Cómo pedir soporte

Abre un ticket en [soporte.ecuafact.com](https://soporte.ecuafact.com/). También puedes consultar el [centro de ayuda](https://ecuafact.com/ayuda/), escribir por [WhatsApp](https://wa.me/593988315544) o usar la [página de contacto](https://ecuafact.com/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](/v1/guias/buenas-practicas#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.

> [!WARNING]
> 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](/v1/guias/buenas-practicas): reintentos con espera exponencial e idempotencia, con código listo para copiar.
- [Límite de request](/v1/guias/limite-de-request): cómo leer `Retry-After` y las cabeceras `X-RateLimit-*`.
- [Comprobantes electrónicos](/v1/guias/emision): las reglas de la Estructura del comprobante que evitan un 422.
- [Respuestas del API](/v1/guias/respuestas): forma de las respuestas exitosas y cabeceras comunes.
