Errores

Todos los errores siguen la misma estructura JSON:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": { }
  },
  "requestId": "58e27d56-a7b4-4243-924c-aab011b4de48"
}

error.code — código estable, legible por máquina.
error.message — descripción breve.
error.details — presente en errores de validación; indica los campos con problema.
requestId — identificador de la solicitud, útil para soporte.

Códigos

HTTP	`code`	Significado
400	`validation_error`	El cuerpo (o un parámetro de ruta, como un `id`) no cumple el esquema. `details` indica los campos con error.
400 / 409 / 422	`downstream_error`	Uvicuo rechazó la operación (datos inválidos, conflicto, etc.). `details` trae el motivo.
401	`unauthorized`	Falta o es inválida la `X-API-Key`. Ver Autenticación.
404	`not_found`	Ruta o recurso inexistente.
422	`no_card_for_employee`	El empleado no tiene ninguna tarjeta asignada en Uvicuo (necesaria para un plan con tarjeta).
429	`rate_limited`	Superaste el límite de uso. Reintenta tras el valor de `Retry-After`.
502	`downstream_error` / `downstream_unavailable`	Problema temporal de Uvicuo. Reintenta más tarde.
500	`internal_error`	Error inesperado.

Casos frecuentes

409 al crear un presupuesto — ya existe un presupuesto con ese name (es único por empresa). Lista los existentes y reutiliza, o usa otro nombre.
422 al activar un plan — validación de negocio fallida; el detalle viene en error.details. Ejemplo: VEHICLE_HAS_NO_TAG (el vehículo no tiene TAG y el presupuesto lo requiere).
409 al activar un plan — el plan no puede activarse en su estado actual (p. ej. ya está activo).