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

# Errors, rate limits and versioning

> How Pascal's APIs report errors, how agents read rate-limit headers and authentication challenges, and how Pascal versions and deprecates endpoints.

Every Pascal API answers in JSON, errors included, so an agent can branch on a code
instead of parsing a page. This page covers the Scene API (`/api/...`), the hosted MCP
server (`/api/mcp`) and the [Pascal API](/docs/developers/api) (`/api/v1`).

## Error bodies

The Scene API and the agent account routes answer with a machine-readable `error` code, a
`message` for people and, when there is a known fix, a `hint`:

```json theme={null}
{
  "error": "unauthorized",
  "message": "Provide a Bearer API key (sk_live_* / sk_test_*) or a valid session cookie.",
  "hint": "Send Authorization: Bearer with a Pascal API key created in Settings."
}
```

The Pascal API uses the OpenAI error shape, with `type`, `code`, `message`, `param` and a
`doc_url`; its codes are listed under [Pascal API errors](/docs/developers/api#errors). The MCP
server answers protocol errors as JSON-RPC errors and tool failures as tool results.

### Unknown routes

A path under `/api` that no route serves answers `404` in the same envelope as the Pascal
API, instead of an HTML page:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "route_not_found",
    "message": "No API route matches GET /api/v2/scenes.",
    "hint": "List Pascal's interfaces at https://editor.pascal.app/.well-known/api-catalog, or read the Scene API at https://editor.pascal.app/api/openapi.json.",
    "doc_url": "https://editor.pascal.app/docs/developers/errors#unknown-routes"
  }
}
```

Its `Link` header points at the [API catalog](https://editor.pascal.app/.well-known/api-catalog)
and the OpenAPI document. A page request for a missing path with `Accept: text/markdown`
gets a Markdown `404` that links the docs, `/llms.txt` and the sitemap.

## Authentication challenges

A request without a valid credential answers `401` with a `WWW-Authenticate` challenge
that points at the [protected resource metadata](https://editor.pascal.app/.well-known/oauth-protected-resource)
(RFC 9728) and names the scopes an authorization request must carry: the resource's own, plus
`offline_access`, which every registered client requests:

```http theme={null}
WWW-Authenticate: Bearer realm="Pascal", resource_metadata="https://editor.pascal.app/.well-known/oauth-protected-resource", scope="offline_access scene:read scene:write"
```

| Challenge | Meaning | What to do |
| - | - | - |
| No `error` | No credential was sent. | Authenticate: see [/auth.md](https://editor.pascal.app/auth.md). |
| `error="invalid_token"` | The credential is expired, revoked or unknown. | Reconnect, or ask the person for a new API key. Don't retry the same credential. |
| `403` with `error="insufficient_scope"` | An OAuth connection called a tool its scopes don't cover. The challenge's `scope` lists what to request. | Ask the person to reconnect and approve the missing scope. |

A connection holding `scene:read` alone can call the read-only tools; `scene:write` covers
the tools that change a project. Each tool's scope is published at
[/.well-known/mcp](https://editor.pascal.app/.well-known/mcp).

## Rate limits

Every response the Scene API and the MCP server count carries the
[IETF rate-limit fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/):
`RateLimit-Policy` names each window and its quota, `RateLimit` its remaining requests
and the seconds until it resets.

```http theme={null}
RateLimit-Policy: "address";q=3000;w=60, "credential";q=120;w=60
RateLimit: "address";r=2987;t=41, "credential";r=107;t=41
```

| Surface | Default budget per minute |
| - | - |
| Scene API and MCP, without a credential | 120 per address (`"address"`) |
| Scene API and MCP, with a credential | 120 per address and credential (`"credential"`), within 3,000 per address (`"address"`) |
| Pascal API (`/api/v1`) | 300 per credential (`"credential"`) |
| Agent registration | 10 per address per hour |

Each request counts against every window listed. Over a limit, the answer is `429` with
`Retry-After` in seconds and nothing ran, so the same request is safe to send again once
that time has passed. The budget per address and credential exists because many people can
reach Pascal from one address: every Claude user arrives from Anthropic's egress range.

## Versioning and deprecation

The Scene API is versioned in its [OpenAPI document](https://editor.pascal.app/api/openapi.json)
(`info.version`) and the Pascal API in its path (`/api/v1`). Within a version, Pascal adds
fields, endpoints, tools and error codes without notice; clients should ignore what they
don't recognise. Removing or renaming a field, changing its meaning, or removing an endpoint
happens only through deprecation:

1. The endpoint is marked `deprecated: true` in the OpenAPI document, and every response from
   it carries a `Deprecation` header (RFC 9745) with the date it was deprecated, a `Link` with
   `rel="deprecation"` to this section, and a `Link` with `rel="successor-version"` to its
   replacement.
2. When a removal date is set, responses also carry a `Sunset` header (RFC 8594) with that
   date, and the change is announced in the [changelog](https://editor.pascal.app/changelog).
3. After the sunset date the endpoint may answer `410 Gone` or be removed.

Currently deprecated:

| Endpoint | Deprecated | Use instead |
| - | - | - |
| `GET /api/auth/agent/invitations` | 2026-08-08 | An agent invite link, redeemed with `POST /api/auth/agent/invites/redeem` |
| `POST /api/auth/agent/invitations/{id}/accept` | 2026-08-08 | `POST /api/auth/agent/invites/redeem` |

Neither has a sunset date yet.

### Request ids

Pascal API and MCP answers carry a `Request-Id` header. Quote it when you
[contact support](https://editor.pascal.app/contact).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.