Casa Layer · Every guest, remembered.

Errors are JSON with a machine-readable error code. Some bodies also include scope or detail.

{ "error": "forbidden", "scope": "read:guests" }

See also: Data model · Pagination

Public codes

Status	Body	Meaning
`400`	`{ "error": "invalid_cursor" }`	The `cursor` is not a valid keyset token. Start from the first page.
`400`	`{ "error": "source_id requires integration_id" }`	You sent `source_id` without `integration_id`. List IDs with `GET /v1/integrations`.
`400`	`{ "error": "invalid_request" }`	The table preview body is missing `member_type` or `filter_doc`.
`401`	`{ "error": "unauthorized" }`	Missing, unknown, or revoked bearer credential.
`403`	`{ "error": "forbidden", "scope": "read:guests" }`	Valid credential, missing scope. `scope` is the first required scope.
`403`	`{ "error": "forbidden" }`	Drill-down `X-Property-Id` is outside the credential’s group.
`403`	`{ "error": "tenant_not_provisioned" }`	The org claim has no property group yet.
`404`	`{ "error": "not_found" }`	No such resource in your scope.
`500`	`{ "error": "internal_error" }`	Unhandled server fault. Retry later.

A guest source_id lookup that finds nothing is not an error. The list returns { "data": [], "next_cursor": null, "has_more": false }. Get-by-ID routes (/v1/guests/{id}, /v1/reservations/{id}, and the other single-resource paths) return 404 when the ID is missing or outside scope.

Session-only codes

These appear when a personal API key or partner token hits a surface that is not public:

Status	Body	Meaning
`403`	`{ "error": "session_required" }`	The route needs a signed-in Casa Layer session (connections, credentials, SQL).
`403`	`{ "error": "mcp_oauth_required" }`	A SPA session token was sent to `/mcp`. Use a personal API key or Casa Layer sign-in.

Casa Layer sign-in tokens (MCP OAuth) cannot call /v1/*. Those requests return 403 forbidden. Use a personal API key or a partner access token.

Endpoint pages in the API reference list the status codes that route can return.