Errores y validaciones

Interpretar errores de la API y reintentar sin duplicar

Los errores de la API llegan en JSON con un código HTTP. Esta guía recoge los que devuelve el programa, qué revisar y cuándo es seguro repetir la petición.

Aplicabilidad: API versión 3 · Plan Profesional, con la API activada en el servicio.

Formatos de error

Hay dos formas según dónde se detecta el error:

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

{ "error": "Registro no encontrado" }

La primera la usan la autenticación y las funciones (crear…, pagar…, exportar…); la segunda, los recursos de datos, que pueden añadir data con el registro afectado. Lee message o error según exista.

Códigos HTTP

HTTP	Ejemplos de mensaje	Qué comprobar	¿Reintentar?
400	«Registro duplicado», «Ningún dato recibido por formulario», «Ha ocurrido un error mientras se guardaban los datos - …», … field is required	Campos, formato de formulario, fechas, clave primaria.	No sin corregir el dato.
401	«Clave de API no válida»	Cabecera Token y clave activa.	No.
403	Sin permiso	Permisos de la clave para ese recurso y método.	No.
404	«Registro no encontrado», recurso inexistente, customer-not-found	Identificador y nombre del recurso (GET /api/3/).	No.
405	method-not-allowed	Método: las funciones crear… usan POST; exportar…, GET.	No.
409	«API desactivada…»	Activación de la API en el servicio.	Tras activarla.
422	record-save-error, error calculando totales	Reglas de negocio del documento.	No sin corregir.
429	«…se ha bloqueado durante 10 minutos el acceso desde su IP»	Fallos de clave o permiso repetidos.	Tras 10 minutos y corregida la causa.
500	API-ERROR: …	Error interno.	Una vez, tras comprobar que no se creó nada.

Reintentar sin duplicar

1. Errores de validación (400, 404, 422) y de configuración (401, 403, 409): corrige y no repitas la misma petición.
2. Tiempo de espera o red cortada en un POST: la operación pudo completarse. Busca el registro (filtro por cliente, fecha, referencia externa) y repite solo si no existe.
3. PUT, DELETE y pagarFactura… se pueden repetir sobre el mismo registro.

Fechas

Envía las fechas como dd-mm-aaaa (el programa también acepta aaaa-mm-dd); las respuestas de los recursos las devuelven como dd-mm-aaaa.

Qué registrar en tu integración

Método, ruta (sin la clave), código HTTP, cuerpo de la respuesta y hora. No guardes la clave ni datos personales completos en los registros.

Si el problema continúa, escribe a soporte indicando el método, la URL sin la clave, el código HTTP, el cuerpo de la respuesta y la hora de la petición. Nunca envíes la clave API.