Errors, rate limits and versioning

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 (/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:

{
  "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. 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:

{
  "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 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 (RFC 9728) and names the scopes an authorization request must carry: the resource’s own, plus offline_access, which every registered client requests:

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.
`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.

Rate limits

Every response the Scene API and the MCP server count carries the IETF rate-limit fields: RateLimit-Policy names each window and its quota, RateLimit its remaining requests and the seconds until it resets.

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 (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:

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.
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.
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.

Integrate

Extend Pascal

Errors, rate limits and versioning

Error bodies

Unknown routes

Authentication challenges

Rate limits

Versioning and deprecation

Request ids

​Error bodies

​Unknown routes

​Authentication challenges

​Rate limits

​Versioning and deprecation

​Request ids

Error bodies

Unknown routes

Authentication challenges

Rate limits

Versioning and deprecation

Request ids