API v1.0.0 · FUNCIONAMIENTO

Errores

Los errores usan el código HTTP real y un cuerpo con un código estable, un mensaje en español y el campo afectado. Esta página explica el formato, cuándo reintentar y la lista completa de códigos.

Formato

Todas las respuestas de error de /v1 tienen el mismo cuerpo, también las de rutas que no existen:

Respuesta 400

{
  "error": {
    "codigo": "VALIDACION",
    "mensaje": "La solicitud tiene 2 campos con errores.",
    "campo": null,
    "detalles": [
      {
        "campo": "items[0].cantidad",
        "codigo": "DECIMALES_EXCEDIDOS",
        "mensaje": "La cantidad admite hasta 2 decimales."
      },
      {
        "campo": "cliente.email",
        "codigo": "FORMATO_INVALIDO",
        "mensaje": "El correo electrónico no es válido."
      }
    ],
    "requestId": "5f0c8e2a-7c1b-4f7e-9a51-3c2d9b8e6a10"
  }
}

Campo	Contenido
`codigo`	Código estable del error. Tu integración debe decidir por este valor, no por el mensaje.
`mensaje`	Descripción en español, para registros o para mostrar a una persona. Puede cambiar de redacción.
`campo`	Ruta del campo o parámetro afectado, por ejemplo `totalEsperado`; `null` si no aplica. Siempre está presente.
`detalles`	En `VALIDACION`, un elemento por campo con su ruta, su código y su mensaje. En los demás errores, una lista vacía.
`requestId`	Identificador de la solicitud, el mismo de la cabecera `X-Request-Id`.

Las respuestas de error nunca incluyen detalles internos. Si escribes a soporte, cita el requestId: con él se ubica la solicitud en los registros de Golem. Puedes enviar tu propio identificador en la cabecera X-Request-Id (hasta 64 caracteres: letras, números y -) para relacionar las solicitudes con los registros de tu sistema.

Lectura estricta del JSON

Un campo que el contrato no define responde 400 VALIDACION con CAMPO_DESCONOCIDO. Así se detectan errores de tipeo como precioUnitaro.
Un número enviado como texto ("7.80") o un decimal en un campo entero responde TIPO_INVALIDO.
Las fechas van como yyyy-MM-dd y deben existir: 2026-02-31 responde 400 VALIDACION.

Las respuestas, en cambio, pueden sumar campos nuevos sin cambiar de versión: tu integración debe ignorar los que no conozca.

Errores de validación y de negocio

400: la solicitud no se puede leer o tiene datos con formato inválido. No se creó nada.
422: los datos tienen el formato correcto pero no cumplen una regla del SRI o de la empresa, por ejemplo una tarifa de IVA que no está vigente, o una cédula inválida cuando la solicitud indica tipoIdentificacion (sin el tipo, una cédula o un RUC inválido responde 400 VALIDACION porque no se puede deducir el tipo). No se creó el comprobante ni se consumió crédito.

Mensajes del SRI

Un comprobante que el SRI devuelve o no autoriza no es un error del API: la emisión responde 201 con el comprobante en estado DEVUELTO o NO_AUTORIZADO, y los motivos del SRI van en su lista mensajes. Ver Estados.

Cuándo reintentar

Respuesta	Qué hacer
`400`, `401`, `402`, `403`, `404`, `413`, `415`, `422`	Corrige la solicitud, el token o la cuenta. Repetir la misma solicitud da el mismo error.
`409 IDEMPOTENCIA_EN_PROCESO`	Repite la misma solicitud después de los segundos de `Retry-After`.
`409 IDEMPOTENCIA_CUERPO_DISTINTO` o `ESTADO_NO_PERMITE`	No reintentes: usa otra `Idempotency-Key` o revisa el estado del comprobante.
`429`	Repite después de los segundos de `Retry-After`.
`500`	En una emisión, repite con la misma `Idempotency-Key`. Sin clave, busca antes el comprobante en el listado por `referencia`.
`503`	Repite después de los segundos de `Retry-After`.
Error de red o tiempo de espera agotado	En una emisión, repite con la misma `Idempotency-Key`.

Para los reintentos automáticos, espera cada vez más entre intentos (por ejemplo 1, 2, 4 y 8 segundos) y respeta Retry-After cuando venga.

Errores de cualquier ruta

Además de los que documenta cada operación, cualquier ruta de /v1 puede responder:

HTTP	Código	Causa
404	`RUTA_NO_ENCONTRADA`	La ruta no existe.
405	`METODO_NO_PERMITIDO`	La ruta no admite ese método; la cabecera `Allow` lista los admitidos.
406	`FORMATO_NO_ACEPTADO`	La cabecera `Accept` no admite el formato de la respuesta.
429	`LIMITE_EXCEDIDO`	Se superó un límite de solicitudes.
503	`MANTENIMIENTO`	Mantenimiento programado, avisado por correo con 24 horas de anticipación.

Lista de códigos

Todos los códigos de error del API, con su causa y cómo resolverlos. Cada código tiene su propio enlace, por ejemplo SIN_CREDITOS.

Códigos de error del API
HTTP	Código	Causa y solución
400	`JSON_INVALIDO`	El cuerpo no es un JSON válido. Revisa la sintaxis cerca de la línea y la columna que indica el mensaje.
400	`VALIDACION`	Uno o más campos no cumplen el formato. `detalles` lista cada campo con su código: `CAMPO_REQUERIDO`, `CAMPO_DESCONOCIDO`, `TIPO_INVALIDO`, `FORMATO_INVALIDO`, `VALOR_INVALIDO`, `LONGITUD_INVALIDA` o `DECIMALES_EXCEDIDOS`. Corrige los campos de `detalles`. Los campos que el API no conoce se rechazan: revisa los nombres.
400	`PARAMETRO_INVALIDO`	Un parámetro de la ruta o de la consulta no es válido: por ejemplo, una clave de acceso sin 49 dígitos, un rango de fechas de más de 366 días o un `cambiadoDesde` anterior a 90 días. Corrige el parámetro que indica `campo`.
400	`IDEMPOTENCY_KEY_INVALIDA`	La cabecera `Idempotency-Key` no tiene entre 8 y 100 caracteres, o usa caracteres distintos de letras, números, `-`, `_`, `.` y `:`. Genera la clave con un UUID v4.
400	`TOKEN_EN_URL`	La URL incluye `token`, `access_token` o `api_key`. Envía el token solo en la cabecera `Authorization`. Revoca ese token y crea otro: la URL pudo quedar en registros.
401	`TOKEN_REQUERIDO`	Falta la cabecera `Authorization`. Envía `Authorization: Bearer <token>`.
401	`TOKEN_INVALIDO`	El token no existe o no tiene el formato de un token de Golem. Copia el token completo, con su prefijo. Si no lo tienes, crea otro: Golem no puede mostrarlo de nuevo.
401	`TOKEN_REVOCADO`	El token fue revocado. Crea otro en Cuenta > API e integraciones.
402	`SIN_CREDITOS`	La empresa no tiene créditos para emitir o reprocesar. Compra una recarga en la aplicación. Las consultas y descargas siguen disponibles.
403	`EMPRESA_SUSPENDIDA`	La empresa no está activa. Afecta a las emisiones y las acciones; las consultas siguen disponibles. Escribe a [email protected].
403	`PUNTO_NO_PERMITIDO`	El token no puede emitir en ese punto de emisión, o está restringido y no tiene puntos. Usa uno de los puntos que devuelve `GET /empresa` en `token.puntosPermitidos`, o cambia los puntos del token en la aplicación.
403	`PLAN_NO_PERMITE`	El plan de la empresa no incluye la emisión de comprobantes electrónicos. Revisa el plan en la aplicación o escribe a [email protected].
404	`NO_ENCONTRADO`	El recurso no existe en la empresa y el ambiente del token, o el catálogo no existe. Revisa la clave de acceso y que el token sea del mismo ambiente en que se emitió el comprobante.
404	`RUC_NO_REGISTRADO`	El catastro del SRI no registra ese RUC. Revisa el número con el proveedor o el cliente.
404	`RUTA_NO_ENCONTRADA`	La ruta no existe en `/v1`. Revisa la URL base (`https://api.golem.ec/v1`) y la ruta.
405	`METODO_NO_PERMITIDO`	La ruta no admite ese método HTTP. Usa uno de los métodos de la cabecera `Allow`.
406	`FORMATO_NO_ACEPTADO`	La cabecera `Accept` no admite el formato de la respuesta. Envía `Accept: application/json` (en las descargas, `application/pdf` o `application/xml`) u omite la cabecera.
409	`IDEMPOTENCIA_CUERPO_DISTINTO`	La `Idempotency-Key` ya se usó con otro cuerpo o en otra ruta. Usa una clave nueva para cada operación distinta y la misma clave solo para repetir la misma solicitud.
409	`IDEMPOTENCIA_EN_PROCESO`	La solicitud original con esa `Idempotency-Key` todavía se está procesando. Repite la solicitud después de los segundos de `Retry-After`.
409	`ESTADO_NO_PERMITE`	El estado del comprobante no permite la operación: descarga de un comprobante no autorizado, reproceso de uno autorizado o reenvío del correo de uno no autorizado. Consulta el estado del comprobante. Para corregir uno no autorizado, emite uno nuevo.
410	`RECURSO_RETIRADO`	La ruta se retiró después de su fecha `Sunset`. Reservado: ninguna ruta de la versión 1 está retirada. Usa la ruta que indica la página de cambios.
413	`CUERPO_DEMASIADO_GRANDE`	El cuerpo supera 256 KB. Reduce el comprobante: admite hasta 200 ítems.
415	`TIPO_CONTENIDO_NO_SOPORTADO`	Una emisión llegó sin `Content-Type: application/json`. Envía el cuerpo como JSON con esa cabecera.
422	`PUNTO_EMISION_NO_EXISTE`	El establecimiento o el punto de emisión que indica la solicitud no existe en la empresa. Usa los códigos que devuelve `GET /empresa`.
422	`IDENTIFICACION_INVALIDA`	La cédula o el RUC no son válidos para el `tipoIdentificacion` indicado, o se indicó consumidor final como sujeto retenido. Sin `tipoIdentificacion`, una cédula o un RUC inválido responde `400 VALIDACION` (`CAMPO_REQUERIDO` en `tipoIdentificacion`), porque no se puede deducir el tipo. Corrige la identificación. Para pasaportes y documentos del exterior, indica `tipoIdentificacion` 06 u 08.
422	`TARIFA_IVA_NO_VIGENTE`	La tarifa de IVA no está vigente en la fecha del comprobante (en notas de crédito, en la fecha de la factura modificada). Usa una tarifa del catálogo `tarifas-iva` vigente en esa fecha.
422	`TARIFA_IVA_NO_COINCIDE`	En una nota de crédito sobre una factura de Golem, un ítem usa una tarifa de IVA que la factura no tiene. Usa en cada ítem una de las tarifas de la factura modificada.
422	`PAGOS_NO_CUADRAN`	La suma de `pagos` difiere del total de la factura en más de 0.01. Ajusta los pagos al total calculado, o usa `formaPago` para un solo pago por el total.
422	`TOTAL_NO_COINCIDE`	El total que calcula Golem difiere de `totalEsperado` en más de 0.01. El mensaje muestra el desglose. Compara el cálculo de tu sistema con el de la guía de facturas; con precios con IVA incluido, revisa la conversión.
422	`DESCUENTO_INVALIDO`	El descuento de una línea supera la cantidad por el precio unitario. Envía el descuento en dólares de la línea completa, sin superar su valor.
422	`CONSUMIDOR_FINAL_EXCEDE_LIMITE`	Una factura a consumidor final supera el tope que permite el SRI. Identifica al comprador con su cédula, RUC o pasaporte.
422	`FECHA_FUERA_DE_RANGO`	La fecha de emisión no es la de hoy ni la de ayer (hora de Ecuador), o es anterior a la del documento modificado o sustento. Omite `fechaEmision` para usar la de hoy. El SRI exige transmitir el comprobante al emitirlo.
422	`FIRMA_NO_VIGENTE`	La empresa no tiene firma electrónica o la firma venció. Carga una firma vigente en la aplicación.
422	`SIN_STOCK`	Un ítem usa un producto con control de inventario sin existencias suficientes. Registra el ingreso en la aplicación o quita el control de inventario del producto.
422	`SUSTENTO_NO_ENCONTRADO`	La factura que modifica la nota de crédito no existe en la empresa y el ambiente del token. Revisa la clave de acceso. Si la factura se emitió fuera de Golem, envía `codDoc`, `numero` y `fechaEmision`.
422	`SUSTENTO_NO_AUTORIZADO`	La factura que modifica la nota de crédito no está autorizada. Emite la nota de crédito cuando la factura esté autorizada.
422	`NOTA_CREDITO_EXCEDE_SALDO`	La nota de crédito, sumada a las anteriores de la misma factura, supera el total de la factura. Reduce el valor de la nota de crédito al saldo de la factura.
422	`CLIENTE_NO_COINCIDE`	La identificación de `cliente` no es la de la factura modificada. Omite `cliente`: se toma de la factura.
422	`CLIENTE_NO_PERMITIDO`	Una nota de crédito a consumidor final, o sobre una factura emitida a consumidor final. El SRI exige un receptor identificado en las notas de crédito.
422	`CODIGO_RETENCION_INVALIDO`	El código de retención no existe o no está vigente para ese impuesto. Usa un código de los catálogos `retenciones-renta` o `retenciones-iva`.
422	`PORCENTAJE_RETENCION_INVALIDO`	Falta `porcentaje` en un código de porcentaje variable, o el porcentaje enviado no coincide con el de un código de porcentaje fijo. Envía `porcentaje` solo en los códigos con porcentaje variable.
422	`SIN_CORREO`	El comprobante no tiene un correo de destino. El correo se toma del comprobante al emitirlo; en ese caso, envía el XML y el RIDE por tu cuenta.
429	`LIMITE_EXCEDIDO`	Se superó un límite de solicitudes por minuto. Repite la solicitud después de los segundos de `Retry-After`.
500	`ERROR_INTERNO`	Error inesperado de Golem. Si ocurrió al emitir, repite la solicitud con la misma `Idempotency-Key`. Escribe a [email protected] con el `requestId`.
503	`SRI_NO_DISPONIBLE`	El SRI no responde. Repite la solicitud después de los segundos de `Retry-After`.
503	`SERVICIO_NO_DISPONIBLE`	Un servicio interno de Golem no responde. Repite la solicitud después de los segundos de `Retry-After`.
503	`MANTENIMIENTO`	Golem está en mantenimiento. Los mantenimientos se avisan por correo con 24 horas de anticipación. Repite la solicitud después de los segundos de `Retry-After`.

Códigos de los detalles

En un error VALIDACION, cada elemento de detalles tiene uno de estos códigos:

Código	Causa
`CAMPO_REQUERIDO`	Falta un campo obligatorio.
`CAMPO_DESCONOCIDO`	El campo no existe en el contrato (el token va en la cabecera, no en el cuerpo).
`TIPO_INVALIDO`	El valor no es del tipo esperado, por ejemplo un texto donde va un número.
`FORMATO_INVALIDO`	El valor no tiene el formato esperado (fecha, correo, código de 3 dígitos).
`VALOR_INVALIDO`	El valor no está entre los permitidos o está fuera del rango.
`LONGITUD_INVALIDA`	El texto o la lista es más corto o más largo de lo permitido.
`DECIMALES_EXCEDIDOS`	El número tiene más decimales de los permitidos.