Errors & conventions

HTTP status

Status	When
400	Invalid body or query (validation).
401	Missing or invalid session / Bearer token.
403	Authenticated but not allowed (role, scope, account grant, or tenant mismatch).
404	Resource not found or hidden by tenant isolation (do not probe across tenants).
409	Conflict (for example, tenant already has an account for that cloud).
422	Semantically invalid parameters (for example, list `limit` above the route max).
429	Rate limited (login and some public endpoints).

Most routes return FastAPI-style JSON:

{ "detail": "…" }

Error messages shown to tenants are sanitized (no paths or secrets).

Many list routes accept limit and offset (or cursor-style params documented per route).
Inventory-style lists often cap limit at 1000.
Prefer meta aggregate routes (/v1/resources/meta/…) for counts and dollars instead of paging full inventory.