ISS-085: ProxmoxVEx endpoints historically use three different success/error shapes. This document standardizes the envelope for new endpoints and describes the migration policy for existing ones.

Standard envelope (new endpoints)

// success
{"ok": true, "data": { ... }}

// error
{"ok": false, "error": {"code": "SOME_CODE", "message": "Human readable"}}

Rules:

ok is a boolean — never rely on HTTP status alone.
error.code is a stable SCREAMING_SNAKE string safe for clients to switch on.
error.message is user-facing; details go in error.details (object, optional).
Lists return {"ok": true, "data": {"items": [...], "total": N}} when paginated.

Legacy envelopes (do not break)

Shape	Example	Policy
`{"success": true, ...}`	`integrations/webhooks.py`	keep; new fields go in the same object
`{"ok": false, "error": {...}}`	`api/licence.py`	already the standard error shape
bare object `{"id": ..., "message": ...}`	`api/site_recovery.py`	keep for compatibility; document per-route

Migration: when a legacy endpoint is touched for other reasons, prefer adding "ok": true/false alongside existing fields rather than renaming, so existing API consumers keep working.

API Response Envelope Convention

Standard envelope (new endpoints)

Legacy envelopes (do not break)