Errores y límites

Formato de error

Los errores de negocio (401, 403, 404, 409, 422) devuelven un objeto con error:

{ "error": "Referencia no registrada en el catálogo: GJ99" }

Dos casos usan el envoltorio por defecto de Fastify, con statusCode, error y message: los 400 de validación de esquema y los 429 de rate limit:

{ "statusCode": 400, "error": "Bad Request", "message": "querystring/limit must be <= 200" }

Algunos errores usan códigos estables para tratarse programáticamente: email_exists, current_password_invalid, invalid_challenge, invalid_code.

Códigos habituales

Código	Cuándo
400	Petición malformada (validación de esquema)
401	Credencial ausente, inválida, revocada o caducada
403	Autenticado pero sin permiso para la acción (p. ej. escritura no-ROOT)
404	No existe o está fuera de tu ámbito (no se distingue, a propósito)
409	Conflicto: duplicado (email, part number, NIF), estado no válido para la acción, sede con equipos
422	Entidad no procesable: referencia inexistente, part number fuera de catálogo, contraseña actual incorrecta
429	Rate limit superado

Rate limiting

200 peticiones/minuto por origen. Las respuestas 429 incluyen las cabeceras estándar x-ratelimit-* con el estado de la ventana.

Paginación

Los listados aceptan limit y offset y devuelven:

{ "items": [], "total": 128, "limit": 50, "offset": 0 }

El limit máximo general es 100–200 según el recurso, con dos excepciones: /v1/devices admite hasta 500 (pensado para el mapa) y /v1/telemetry hasta 2000 (series históricas).