Skip to content

Errores ​

Las respuestas de error son JSON con success: false y un message que explica la causa. Cuando hay varios errores de validación en una misma solicitud, suelen venir juntos en message, separados por espacios (algunas operaciones los devuelven en un arreglo; ver cada página).

json
{
  "success": false,
  "message": "El campo Correo del Cliente en la guía 123456 es obligatorio."
}

Códigos HTTP ​

HTTPSignificado
200Solicitud procesada. En las operaciones por lote puede haber documentos rechazados (por ejemplo, duplicados): revisa la lista de errores de la respuesta.
400Datos inválidos o faltantes. message indica el campo.
401Token ausente, inválido o vencido. Pide un token nuevo.
404La operación no existe (URL mal escrita), o no se encontró el negocio, la factura o el cliente indicados.
409Conflicto: el número de documento ya está registrado (o todo el lote lo estaba), no quedan números de control, se alcanzó el límite del plan, u otra emisión del mismo tipo está en curso (reintenta en unos segundos).
412El token no corresponde al negocio.
500Error al guardar o error interno. Si se repite, contacta a soporte con la hora y la operación.

Regla práctica

Considera exitosa una solicitud solo si el HTTP es 200 y success es true, y revisa las listas de errores por documento que traen las operaciones por lote. Ante un 4xx/5xx, lee igualmente el cuerpo JSON: message explica la causa.

Autenticación ​

HTTPMensajeCausa
400El token de autorización es obligatorio.Falta el encabezado Authorization.
400El formato del token es inválido.El encabezado no tiene la forma Bearer <token>.
401Usuario no autorizado.El token no es válido para ningún negocio.
401Token expiradoEl token venció (dura una hora). Pide uno nuevo.
401Firma del token inválidaEl token fue modificado o no lo emitió este servicio. Pide uno nuevo.
401Token inválido o ausente.Variante usada por Enviar documento, Anular factura y Anular retención.
412Documento rif incorrectoEl token no corresponde al RIF del negocio.

INFO

Algunas respuestas traen además la clave antigua status (errores de token, métodos de pago, bancos, facturas, códigos ISLR) o Mensaje (emisión de retenciones). Todas incluyen también success y message con el mismo valor: usa siempre success/message.

Al pedir el token (Solicitar token):

HTTPMensaje
401No introdujo usuario y/o Contraseña.
401No existe coincidencia de usuario en la Base de Datos.

Negocio emisor ​

MensajeCausa
Tipo de contribuyente no establecido. Para continuar con la emisión de documentos fiscales, es necesario establecer el tipo de contribuyente…El negocio no tiene configurado su tipo de contribuyente. Contacta a soporte de CG Imprenta Digital.
No se encontró el negocio asociado al usuario.El usuario de API no tiene un negocio activo.
No existe un número de control asociado al comercio. · El comercio no posee más números de control activos. · No hay números de control disponibles.(409) Se agotaron los números de control del negocio. Hay que adquirir más antes de emitir.

Cuerpo de la solicitud ​

Mensaje (ejemplos)Causa
Json de facturas no enviado. · Json de guías de despacho no enviado.(400) El cuerpo llegó vacío. Verifica Content-Type: application/json.
El JSON enviado es inválido o está mal formado.JSON con comas sobrantes, comillas faltantes, etc.
El campo … es obligatorio.Falta un campo obligatorio; el mensaje indica cuál y en qué documento.
Cantidad de Facturas Incorrecta.(400) El campo de cantidad no coincide con la cantidad de documentos enviados en el lote.

API de Facturación · CG Imprenta Digital