> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casa-layer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes and machine-readable error bodies on the public API.

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

```json theme={null}
{ "error": "forbidden", "scope": "read:guests" }
```

See also: [Data model](/data-model) · [Pagination](/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](/api-keys) or a
[partner access token](/partner-credentials).

<Info>
  Endpoint pages in the [API reference](/api-reference/introduction) list the
  status codes that route can return.
</Info>