07 — Errores y validaciones

La API devuelve siempre JSON en la respuesta (excepto en descargas de PDFs y exportaciones binarias). Cuando algo falla, la respuesta incluye un código HTTP distinto a 2xx y un mensaje descriptivo del problema.

Códigos HTTP

Código	Significado	Cuándo aparece
200 OK	Operación correcta	GET, POST, PUT, DELETE con éxito (también en creaciones — no usa 201)
400 Bad Request	Petición mal formada	Validación de modelo falla, falta de campos requeridos, tipos incorrectos
401 Unauthorized	Sin autenticación	Cabecera Token ausente o clave inexistente/desactivada
404 Not Found	Recurso no encontrado	El <id> no existe en ese modelo, o la ruta del endpoint es incorrecta
405 Method Not Allowed	Verbo no permitido	Ej. usar DELETE en un endpoint que solo acepta GET/POST
500 Internal Server Error	Error del servidor	Bug, problema de BBDD, fallo inesperado

⚠️ La API devuelve siempre HTTP 200 en operaciones de creación correctas (no 201). Esto es parte de su comportamiento — distinto a otras APIs REST.

Estructura de los errores

Según el tipo de error, la respuesta usa una de estas tres estructuras. Documentamos a continuación cada una con un ejemplo real para que tu cliente las maneje todas.

Error 401 — Token inválido o ausente

{
  "status": "error",
  "message": "Clave de API no válida"
}

El mensaje es el mismo tanto si la cabecera Token falta como si la clave existe pero no es válida.

Error 404 — Registro no encontrado

{
  "error": "Registro no encontrado"
}

Error 400 — Validación del modelo

Cuando intentas crear o modificar un registro con datos inválidos, recibes el error + el objeto que intentaste guardar (útil para depurar):

{
  "error": "Ha ocurrido un error mientras se guardaban los datos - El campo nombre de la tabla clientes no puede ser nulo",
  "data": {
    "codcliente": "TEST02",
    "nombre": null,
    "cifnif": null,
    "regimeniva": "General",
    "personafisica": true
  }
}

El mensaje siempre tiene un prefijo genérico (“Ha ocurrido un error mientras se guardaban los datos - ”) seguido del detalle real. Para extraer el detalle en tu código usa una expresión regular sobre el prefijo:

const match = response.error.match(/^Ha ocurrido un error mientras se guardaban los datos - (.+)$/)
const detalle = match ? match[1] : response.error

Errores frecuentes

Llamada sin versión de API

Si llamas a la API sin indicar versión, recibes un 404 Not Found:

curl https://miempresa.beply.es/api/clientes \
  -H "Token: a1b2c3d4..."
# {"error":"API-VERSION-NOT-FOUND"}

❌ GET /api/clientes ✅ GET /api/3/clientes

401 Unauthorized — token ausente o inválido

Has olvidado autenticarte o has usado una clave incorrecta:

curl https://miempresa.beply.es/api/3/clientes
# {"status":"error","message":"Clave de API no válida"}

Solución: añade -H "Token: <tu-api-key>" con una clave válida y activa.

404 Not Found — registro inexistente

curl https://miempresa.beply.es/api/3/clientes/99999 \
  -H "Token: a1b2c3d4..."
# {"error":"Registro no encontrado"}

400 Bad Request — validación de modelo

Al crear o actualizar un registro, las validaciones del modelo se ejecutan y pueden fallar. Los motivos típicos:

• Campo obligatorio vacío — el modelo declara is_nullable: NO
• Longitud excedida — el campo es varchar(8) y has enviado 12 caracteres
• Tipo incorrecto — el campo espera un entero y has enviado texto
• Restricción de unicidad — ya existe otro registro con esa clave primaria
• Restricción de negocio — ej. CIF/NIF inválido, fecha en el futuro cuando no debe…

400 Bad Request — borrado con dependencias

Al borrar un recurso que tiene registros relacionados (ej. un cliente con facturas, un producto en pedidos), recibes un 400 con la dependencia en el mensaje:

{
  "error": "Ha ocurrido un error mientras se guardaban los datos - No se puede eliminar el cliente porque tiene facturas asociadas"
}

Para resolverlo: borra primero las dependencias o marca el recurso como inactivo (activo: false) en vez de eliminarlo.

Cómo validar antes de enviar

Para evitar errores de validación, consulta el esquema del modelo antes de crear/modificar registros:

GET /api/3/clientes/schema

Te devuelve qué campos son obligatorios (is_nullable: NO), sus tipos y longitudes. Ver 03 — CRUD básico → schema.

Reintentos y idempotencia

• GET, PUT, DELETE son idempotentes: puedes reintentarlos sin temor a duplicar.
• POST no es idempotente por defecto: dos POST crearFacturaCliente con los mismos datos crearán dos facturas distintas. Implementa tú la deduplicación si tu integración puede generar duplicados (ej. guardando el ID externo de tu sistema en un campo observaciones y consultando primero por filtro).

Rate limits

La API no impone límites estrictos por defecto en la mayoría de las instancias. Si tu integración va a hacer mucho volumen (>100 req/min sostenidas), contacta con soporte antes para coordinarnos y evitar problemas.

Logs y trazabilidad

Cada petición a la API queda registrada en el log interno de Beply, incluyendo:

• API Key usada
• Endpoint llamado
• Código HTTP devuelto
• Timestamp

Tu administrador puede consultar estos logs desde el panel — útil para depurar integraciones o auditar accesos.

Soporte

Si te encuentras con un error que no entiendes:

1. Revisa el message de la respuesta
2. Consulta el esquema del modelo
3. Contacta con soporte técnico en https://beply.es/contacto indicando:
   • El endpoint exacto
   • La petición (sin tu API Key)
   • El código y mensaje de error recibidos