Operar

Errores

Qué significa cada código de respuesta y cómo se ve su cuerpo.

Todas las respuestas de error traen statusCode, message y error; algunas agregan un code estable. Tu sistema decide con statusCode y code. El campo error siempre llega, pero es texto libre de diagnóstico: su valor puede cambiar sin aviso, así que no lo compares. Por eso los ejemplos de esta guía lo omiten. La Referencia lista, en cada operación, los códigos que puede responder.

400 — la petición no es válida

El cuerpo, un parámetro, una referencia o el id de la ruta no cumple el contrato. message es una lista con el primer problema de cada campo, nombrado con su ruta dentro del cuerpo:

{
  "statusCode": 400,
  "message": ["data.header.documentType debe ser cualquiera de las siguientes opciones: 'CCF', 'FCF', 'NC', 'FEX'."]
}

Corrige la petición antes de reenviarla: repetirla igual da el mismo 400.

Crear una venta o una compra, y crear o actualizar un vendedor, responden además 400 propios. Cada uno trae message como un solo texto (no una lista) y un code estable con el que tu sistema distingue el caso:

  1. REFERENCE_NOT_FOUND (venta, compra y vendedor): un registro del catálogo que citas por su UUID no existe en tu empresa o fue eliminado; message nombra el recurso y no se escribe nada. En una compra, también lo recibes si envías como objeto el proveedor o la condición de pago con el id de un registro que tu empresa eliminó. En un vendedor, lo recibes cuando la zona que citas en zone no existe en tu empresa o fue eliminada.
  2. INSUFFICIENT_DATA_TO_CALCULATE (venta): a la venta le faltan datos para su modo, o trae alguno que ese modo no admite; message nombra el campo.
  3. AMOUNT_OUT_OF_TOLERANCE (venta): un monto enviado no coincide al centavo con el que corresponde; message nombra el campo, lo que enviaste y el valor correcto.
{
  "statusCode": 400,
  "message": "El proveedor indicado no existe o fue eliminado.",
  "code": "REFERENCE_NOT_FOUND"
}
{
  "statusCode": 400,
  "message": "totals.totalPagar: se envió 7789.89; el valor correcto es 7720.95.",
  "code": "AMOUNT_OUT_OF_TOLERANCE"
}

Crear una compra puede responder también un 400 sin code cuando el documento no pasa la validación electrónica: message es un solo texto con el motivo. Si el motivo es la configuración de facturación electrónica de tu empresa (certificado o contraseñas), corregir la petición no basta: pide al equipo de Openbox Cloud que la revise. Ese 400 llega después de crear o actualizar el proveedor o la condición de pago que enviaste como objeto.

Consultar y anular una venta responden también 400 cuando la venta no existe en tu empresa. Anular responde además 400 cuando el estado de la venta no permite anularla (por ejemplo, ya anulada, pagada o en contingencia).

401 — sin sesión válida

Falta el token, venció o fue revocado por un inicio de sesión posterior con la misma llave. Inicia sesión una vez y repite la petición (Autenticación). Al iniciar sesión, el 401 significa que la llave o el secreto no son válidos.

403 — sin permiso

Tiene dos causas:

  1. El token no corresponde a una llave de API de Partners.
  2. La llave no tiene acceso al módulo del recurso (clientes, proveedores, servicios, inventarios, facturación o compras), o no tiene perfil o empresa asignados.

No se resuelve reintentando: pide al equipo de Openbox Cloud que revise el perfil de tu llave. Qué módulo exige cada recurso está en Permisos por módulo.

404 — el registro no existe

El registro que pides no existe en tu empresa. Lo responden consultar, actualizar y eliminar en los ocho recursos del catálogo y consultar una compra. Consultar o anular una venta responden 400 en ese caso (ver arriba).

409 — conflicto con un registro existente

El 409 llega con code o sin él, y la causa cambia. Ninguno se resuelve repitiendo la petición igual.

Con code: INTERNAL_ID_DUPLICATED

{
  "statusCode": 409,
  "message": "Ya existe un registro activo con el internalId indicado.",
  "code": "INTERNAL_ID_DUPLICATED"
}

message siempre habla del internalId, pero el 409 tiene tres causas y en ninguna se escribe nada:

  1. Otro registro activo de tu empresa ya usa ese internalId (al crear o actualizar en el catálogo): búscalo por tu internalId y actualízalo.
  2. El id que enviaste al crear en el catálogo ya existe: consulta el registro por ese id. Si lo encuentras, es tuyo: actualízalo. Si responde 404, es de otra empresa o lo eliminaste: créalo sin id y Openbox Cloud genera uno.
  3. Una venta o una compra lleva un registro como objeto con un id de otra empresa: no se crea ni el registro ni el documento. Envía ese registro sin id o cita por referencia uno de tu empresa.

Sin code

Crear una venta o una compra responde 409 sin code cuando ya existe una con el mismo internalId en un estado que impide recrearla. Consúltala por tu internalId y usa la que ya existe: Reintentos explica cómo con una venta y con una compra.

Eliminar una zona que tiene vendedores asignados, activos o inactivos, responde 409 sin code y la zona sigue igual. message nombra la zona. Elimina o cambia de zona a sus vendedores antes de eliminarla:

{
  "statusCode": 409,
  "message": "No se puede eliminar la zona \"Zona Central\" porque tiene vendedores asociados"
}

501 — NOT_AVAILABLE_YET

La operación, o la forma de la petición que enviaste, está declarada en el contrato y responde así mientras su insignia no cambie. No crea ni cambia nada.

{
  "statusCode": 501,
  "message": "Esta operación aún no está disponible. Se habilitará cuando su funcionalidad se publique.",
  "code": "NOT_AVAILABLE_YET"
}

No es reintentable: qué significa cada insignia y cuándo deja de responder 501 está en Disponibilidad.

Copyright © 2026