Errores
Todo error responde el mismo cuerpo.
{
"message": "El cliente no está registrado en la empresa.",
"code": "customer_not_found",
"errors": { "customer": ["El cliente no está registrado en la empresa."] }
}
messagees texto para personas y cambia con el idioma. Nombra el valor recibido, la línea o el pago por su posición y el catálogo por su nombre: "La cantidad de la línea 2 debe ser mayor que 0, y llegó 0.".codeestá presente en todo error y es estable. El sistema integrado decide porcode. Los casos sin nombre propio usanvalidation_failed(422) ynot_found(404).errorsaparece en los 422 y nombra los campos tal como los envió el integrador (lines.0.product,address.department).- Un recurso de otra empresa responde igual que uno inexistente: 404
not_found.
Códigos de error
code |
HTTP | Cuándo |
|---|---|---|
invalid_api_key |
401 | Llave ausente, mal formada o desconocida. |
api_key_revoked |
401 | Llave revocada. |
missing_scope |
403 | La llave no tiene el alcance de la ruta, indicado en scope. |
module_inactive |
403 | La empresa no tiene activo el módulo Facturación por API. |
company_access_suspended |
403 | El acceso de la empresa venció o está suspendido. |
company_contract_terminated |
403 | El contrato de la empresa terminó: las lecturas responden y las escrituras se rechazan. |
action_not_allowed |
403 | Los permisos de la llave no alcanzan para esa operación sobre ese registro. |
sale_of_another_branch |
403 | La llave está atada a una sucursal y la venta es de otra; el mensaje nombra la sucursal de la venta. Rige al leer la venta, al leer, emitir o enviar su documento, al emitirle una nota y al invalidar la venta o una nota, y también cuando la replacement_sale de una invalidación es de otra sucursal. |
batch_of_another_branch |
403 | La llave está atada a una sucursal y el lote lo envió una llave de otra; el mensaje nombra la sucursal del lote. |
rate_limited |
429 | Más de 120 peticiones por minuto, más de 20 PDF por minuto, o un PDF caro mientras otro se genera; se espera lo que diga Retry-After. |
document_too_long |
422 | El documento pasa de 100 líneas o de 100000 caracteres de descripción y su PDF no sale por API. De una venta, sellado o firmado en contingencia: POST /sales/{uuid}/document/send; lo demás, pedirlo desde el panel. |
malformed_json |
400 | El cuerpo se envió como JSON (Content-Type: application/json) y no se puede leer, por ejemplo cortado o con una coma de más. No se valida ningún campo. |
idempotency_key_required |
400 | Idempotency-Key ausente o fuera de 1 a 128 caracteres visibles. |
idempotency_key_reused |
409 | La llave ya se usó con otro cuerpo. |
idempotency_request_in_progress |
409 | La primera petición con esa llave sigue en curso. |
customer_already_exists |
409 | Documento o code ya registrado; el cliente va en data. |
sale_reference_exists |
409 | Ya existe una venta vigente con esa reference; la venta va en data, que es nulo si la venta es de otra sucursal que la de la llave. |
product_already_exists |
409 | code ya registrado; el producto va en data. |
validation_failed |
422 | Campo ausente o inválido sin otro nombre; detalle en errors. |
not_found |
404 | El recurso no existe en la empresa. |
method_not_allowed |
405 | La ruta no admite el método; Allow lista los admitidos. |
customer_not_found |
422 | El customer de la venta no está registrado. |
customer_incomplete_for_ccf |
422 | Al cliente le falta NIT, NRC, actividad económica o dirección para un CCF. |
product_unavailable |
422 | Producto inexistente, inactivo o no vendible, en errors.lines.N.product. |
credit_days_required |
422 | Venta a crédito sin credit_days. |
payments_do_not_match |
422 | Los pagos no suman lo que paga el comprador; detalle en errors.payments. |
document_already_issued |
422 | La venta ya tiene documento. |
duplicate_in_batch |
200 | error_code de un elemento de lote cuyo code se repite. |
batch_too_large |
422 | Lote de ventas con más de 1.000 ventas. |
sale_reference_required |
422 | Venta de un lote sin reference. |
duplicate_reference |
422 | reference repetida dentro de un lote. |
price_changed |
422 | El unit_price esperado difiere del vigente; ver price_changes. |
unknown_catalog |
404 | El catálogo no existe. |
unsupported_filter |
422 | El catálogo no admite el filtro. |
document_not_issued |
404 | La venta no tiene documento, o solo uno rechazado: no hay nada que esperar. En la ruta del PDF responde lo mismo un documento en curso (pending, o pending_contingency sin firma): se pide de nuevo hasta que pdf_url traiga el enlace. document.status.value de GET /sales/{uuid} dice cuál de los dos es. |
document_not_sealed |
422 | El documento sigue en contingencia o fue rechazado. |
document_already_invalidated |
422 | El documento ya fue invalidado. |
invalidation_past_deadline |
422 | Venció el plazo: tres meses para una Factura, el décimo día hábil del mes siguiente para un CCF. |
document_has_adjustment_notes |
422 | La venta tiene notas vigentes; se invalidan primero. |
document_has_return_events |
422 | La venta tiene devoluciones registradas; se retiran primero. |
replacement_required |
422 | El tipo de invalidación exige replacement_sale. |
replacement_not_found |
422 | La venta de reemplazo no existe o no tiene documento. |
replacement_invalid |
422 | La venta de reemplazo es la misma, de otro tipo o receptor, no está sellada o es anterior, o el tipo de invalidación no lleva reemplazo (tipo 2, o una nota de crédito). |
replacement_already_used |
422 | La venta de reemplazo ya reemplaza al documento de otra venta: cada documento invalidado se corrige con uno nuevo. |
exchange_in_course |
422 | Hay un cambio de mercadería en curso sobre el documento. |
remittance_goods_arrived |
422 | La mercadería de la remisión ya llegó. |
credit_note_refund_not_returned |
422 | Se devolvió dinero contra la nota desde la pantalla. Invalidarla desde la pantalla, que registra el dinero que vuelve. |
gift_card_already_used |
422 | La venta incluye una tarjeta de regalo ya usada. |
invalidation_refused |
422 | Otra causa impide invalidar; detalle en message y errors.document. |
invalidation_rejected |
422 | Hacienda rechazó la invalidación; razones en errors.document. |
hacienda_setup_invalid |
422 | Hacienda rechazó las credenciales o el certificado de la empresa. |
hacienda_unavailable |
503 | Hacienda no responde. No se invalidó nada. |
adjustment_note_requires_ccf |
422 | La nota solo se emite sobre un CCF. |
adjustment_note_no_accepted_document |
422 | El CCF aún no está aceptado por Hacienda. |
adjustment_note_rejected |
422 | Hacienda rechazó la nota; la llave de idempotencia se devuelve. |
product_not_in_sale |
422 | Una línea de la nota nombra un producto que la venta no tiene. |
adjustment_note_reference_exists |
409 | Otra nota vigente de la venta tiene esa reference; la nota va en data. |
adjustment_discount_exceeds_total |
422 | Los discounts, con los de las notas vigentes, superan el total del CCF. |
adjustment_credit_exceeds_document |
422 | La nota de crédito, con las notas de crédito vigentes, acredita más gravado, exento, no sujeto o IVA de los que tiene el CCF; errors.lines o errors.discounts nombra el monto que se agotó y cuánto queda. |
adjustment_discount_needs_taxed_sale |
422 | El CCF no tiene ventas gravadas. |
adjustment_note_document_being_invalidated |
422 | El CCF tiene una invalidación enviada a Hacienda, sellada o todavía sin respuesta, y no admite notas. Si quedó sin respuesta, volver a enviarla para saber cómo terminó. |
adjustment_gift_card_line |
422 | Una línea de la nota vendió una tarjeta de regalo; errors.lines la nombra. La tarjeta se anula por sí misma, o invalidando el CCF completo si no se usó. |
adjustment_note_not_found |
404 | La nota no pertenece a la venta. |
document_action_in_progress |
409 | Otra acción sobre la venta está en curso; repetir tras Retry-After. |
document_state_changed |
409 | El documento cambió durante la petición. |