Successful Response

Authentication failed. No Authorization: Bearer header, malformed JWT, expired passport, or invalid signature. Identity is not established—unlike 403, the caller is not treated as an authenticated subject. Typical error.code values: INVALID_AUTHORIZATION, AUTHORIZATION_EXPIRED.

Authorization failed. The bearer token was accepted, but the caller lacks required OAuth scopes or permissions, or an upstream service denied access to the resource. Typical error.code values: MISSING_PERMISSIONS, UPSTREAM_ACCESS_DENIED.

Resource not found. The path id does not exist, a parent resource in a nested URL is missing, or the object is not visible. Typical error.code: RESOURCE_NOT_FOUND.

Unprocessable entity (422). Invalid path, query, and body parameters (FastAPI/Pydantic). Domain validation (DomainValidationError and subclasses). Missing context (e.g. MISSING_PARENT_ID, MISSING_REQUIRED_VALUE). All 422 responses share the same {"error": {"code", "message", "correlation_id", "details", "documentation_url"}} envelope; code and details vary by error origin.

Rate limiting (reserved). This BFF process does not currently return 429. Clients that reach the API through a gateway or CDN should still be prepared for 429 and Retry-After from those layers.