Requests require current workspace access and explicit credential scopes. No public production endpoint is configured. This reference applies to the implemented product contract.
REST error envelope
Handled REST errors return {"error":{"message":"…","code":"…"}}. message is present. code is optional on notebook, workspace, and some billing or operator errors. Do not parse human-readable messages as stable identifiers.
| Status | Meaning |
|---|---|
400 |
Invalid input or multiple credential types. |
401 |
Missing, invalid, expired, revoked, or insufficiently scoped API key credentials. |
402 |
Insufficient credits. No paid response or debit commits. |
403 |
Insufficient authority or a rejected session origin. |
404 |
Record unavailable within the authorized workspace. |
409 |
Version or idempotency conflict, expired receipt, or incompatible state. |
429 |
Request allowance exceeded. Wait for Retry-After. |
503 |
Required configuration, source, or service unavailable. |
JSON bodies contain one object. Unknown fields and trailing JSON values are rejected. Bodies are bounded to 1 MiB. Path IDs require URL encoding. The configured deployment’s /api/openapi.json contains route-specific details.
MCP tool errors
Tool errors set isError. Domain errors return text code: message and structuredContent.error with code, message, retryable, and action. Schema errors can occur before a handler runs. Correct the named argument against the current tool schema.
Recover by error code
| Code or condition | Recovery |
|---|---|
invalid_input or schema validation |
Correct the named field. Read current schemas and source vocabulary. |
idempotency_conflict |
Restore the original credential and complete arguments for a retry. |
receipt_expired |
Confirm a new operation and its cost before generating a new key. |
source_release_changed |
Confirm the new search and cost before starting with a new key. |
evidence_changed, cost_confirmation_required |
Refresh availability and approve the new evidence and maximum cost. |
insufficient_credits |
Read current usage if permitted. Ask a workspace manager to restore available credits. |
not_found |
Use a current ID. Never reconstruct suppressed records from an old receipt. |
unauthorized, forbidden, workspace_unavailable |
Restore membership, key scope, or OAuth consent. |
source_busy, directory_unavailable, service_unavailable |
Wait with bounded backoff. Keep the original operation key and arguments. |
HTTP 429 |
Respect Retry-After. Retry with the same operation key. |
A failed lookup is not permission to invent a result, relax criteria, or use an unrelated identity. On a workspace edit conflict, reload the current version before an intentional update.
Request budgets
REST and MCP share a workspace token bucket with a 120-request burst and a refill of 10 per second. Actor buckets allow a 30-request burst with a refill of 2 per second. Browser and OAuth calls from the same user share an actor bucket. Keys use their credential actor and additionally have a 120-per-minute fixed-window limit.
Free reads, documentation, initialization, and retries consume request allowance. Every MCP HTTP request counts. MCP accepts one JSON-RPC operation per request and rejects batches. A throttled call spends no credits. Credit purchases do not raise request limits. Remaining request tokens are not exposed.
Retain safe diagnostics
Record the error code, time, operation reference, and source release. Exclude credentials, private identity responses, protected contact values, action tokens, and database errors. A receipt’s recorded balance is historical. Read current billing usage for available credits.