Errores comunes al emitir por la API (api_key y API v2)

API de emisión directa (api_key)

Esta es la API «clásica»: envías el JSON del comprobante junto con el api_key del punto de emisión. Las respuestas de error tienen la forma {"creado": false, "errors": {"error": "..."}}.

Errores de entrada (antes de procesar el comprobante)

• «Api_key Vacio»: no enviaste el campo api_key en la petición.
• «Api_key No existe»: el valor que enviaste no corresponde a ningún punto de emisión activo (clave incorrecta, con espacios, o el punto de emisión fue eliminado o desactivado). Revisa la clave en Configuración → Puntos de Emisión.
• «Json Invalido -- Json Corrupto»: el cuerpo de la petición no se pudo leer como JSON (comillas sin cerrar, coma final, encabezado Content-Type incorrecto). Valida el JSON con cualquier validador antes de enviarlo.
• «La fecha no debe estar vacia»: el campo emisor.fecha_emision es obligatorio.
• «El secuencial no puede estar vacio»: el campo emisor.secuencial es obligatorio, salvo que envíes emisor.manejo_interno_secuencia = "SI" para que el sistema lo asigne él mismo.

«La longitud de la identificacion no corresponde al tipo de identificacion»

El tipo de identificación del comprador debe coincidir con la cantidad de dígitos enviada:

• 04 (RUC): 13 dígitos, solo números.
• 05 (Cédula): 10 dígitos, solo números.
• 06 (Pasaporte): alfanumérico.
• 07 (Consumidor final): usa la identificación genérica 9999999999999.

Valida el formato del documento del cliente en tu sistema antes de enviarlo a la API, para no descontar un intento fallido.

«Su plan … no permite emitir por API (solo desde la web)»

Los planes de entrada (Micro, Mini, Básico, Esencial) no incluyen emisión por API; solo el plan gratuito de registro y los planes con la característica de API la permiten. También puede salir «Su plan … no incluye …» si tu plan no admite ese tipo específico de comprobante. Solución: sube de plan desde Suscripciones o consulta a tu proveedor.

«Alcanzó el límite anual de comprobantes por API de su plan»

Los planes ilimitados y contables tienen, además del cupo normal, un tope anual de comprobantes que se pueden emitir específicamente por API (proporcional a los meses contratados). Al agotarse ese tope, la API se bloquea pero seguirás pudiendo facturar desde la web con el mismo plan. Para seguir emitiendo por API, contrata comprobantes adicionales (en contrataciones de un año o más) o emite esos comprobantes desde la web mientras renuevas.

«No dispone de comprobantes…» / «Usuario Bloqueado o Mantiene Deuda»

«No dispone de comprobantes…» aparece cuando tu plan ya no tiene cupo o venció; el mensaje detalla cuántos comprobantes usaste y de qué plan, para que sepas qué renovar o ampliar. En el ambiente de pruebas los comprobantes no se descuentan del plan, pero si tu plan ya está en cero, la API los rechaza igual (las pruebas no te salvan de un plan agotado).

«Usuario Bloqueado o Mantiene Deuda con financiero» aparece si la cuenta tiene una deuda pendiente o está bloqueada por el área financiera: regulariza el pago con tu proveedor para poder seguir emitiendo.

API v2 (credenciales con permisos)

La API v2 usa credenciales propias (no el api_key del punto de emisión) enviadas en la cabecera X-Api-Key, como token Bearer, o en el campo api_key2. Sus respuestas siempre tienen la forma {"ok": false, "error": {"codigo": "...", "mensaje": "..."}}: el codigo es fijo y pensado para que tu integración decida qué hacer; el mensaje es para que una persona lo entienda.

• credencial_invalida (401): «Falta la credencial. Mándela en la cabecera 'X-Api-Key'.» si no enviaste ninguna, o «La credencial no es válida o fue revocada.» si la enviaste pero no existe o fue revocada. Crea o revisa tus credenciales en Configuración → Credenciales API.
• sin_permiso (403): «Esta credencial no tiene el permiso «…» (…). El dueño de la cuenta puede crear una con ese permiso.» si la credencial tiene permisos limitados y la operación que pediste no está entre ellos; o «Esta credencial solo se puede usar desde las IP autorizadas…» si la llamaste desde una IP distinta a las que el dueño de la cuenta autorizó.
• demasiadas_peticiones (429): superaste el límite de peticiones por minuto permitido para tu plan o credencial. Espera y reintenta; este error sí es reintentable.
• Otros códigos que puedes recibir: cupo_agotado (402, tu plan se quedó sin comprobantes), plan_no_incluye (402, tu plan no tiene esa función), datos_invalidos/parametro_invalido (422, revisa los campos enviados), documento_no_editable (409, el documento ya no admite cambios) y sri_no_disponible (503, el SRI no está respondiendo; este sí conviene reintentar más tarde).