Errors and response contracts

HTTP invocation failures return one structured error:

{
  "error": {
    "code": "CAPACITY_EXCEEDED",
    "message": "Capacity exceeded. Retry shortly.",
    "details": { "retryAfterSeconds": 5 }
  }
}

Branch on error.code, not the message. Successful REST responses keep their endpoint-specific values: rows, arrays, aggregates or JSON null. There is no success envelope added to REST.

HTTP codes

HTTP status	Code	Meaning / details
400	VALIDATION_ERROR	Invalid request fields. details.issues contains path, code and a safe message.
400	MALFORMED_REQUEST	Malformed request body; also missing/invalid signed webhook input.
400	BLOCKED_URL	URL rejected by the public-address policy before admission.
401	UNAUTHENTICATED	Missing, malformed, invalid or revoked credential.
403	FORBIDDEN	API-key authentication used for a signed-in-user endpoint.
404	NOT_FOUND	Resource missing or outside caller scope; also unconfigured OAuth discovery.
405	METHOD_NOT_ALLOWED	Unsupported MCP HTTP method; Allow: POST is included.
402	QUOTA_EXCEEDED	Insufficient credits; details contain creditsLimit, creditsUsed, creditsRemaining.
503	CAPACITY_EXCEEDED	Admission capacity exhausted; details contain retryAfterSeconds, with matching Retry-After header.
503	SERVICE_UNAVAILABLE	Readiness dependency is unavailable.
502	UPSTREAM_ERROR	Upstream operation failed, such as OAuth metadata retrieval.
500	INTERNAL_ERROR	Unexpected failure. The response contains a fixed message rather than exception diagnostics.

Validation paths retain schema field names and numeric array indices; dynamic record keys can appear as *. Submitted values and raw exception messages are not included. Quota rejection currently reports creditsRemaining: 0. Error details depend on the code, so do not assume every error contains them.

MCP HTTP authentication failures retain the WWW-Authenticate discovery challenge. Successful Stripe webhook processing returns an empty 204; invalid verification returns 400, while unexpected processing failure returns 500.

Invocation failure versus job outcome

An accepted scrape can fail at a target URL. That failure is stored in the job/result and is distinct from the invocation error above. A completed HTTP 200 scrape/analyse array can contain successful and failed entries. Map can return usable sitemaps alongside an aggregate error. Stored job diagnostics keep their existing message, name, stack and cause shape; they are not converted into invocation codes.

HTTP 202 means work was accepted and is still being waited on, or immediate return was requested. Submission responses contain the original jobs. Poll those IDs; do not submit again. Result reads can return JSON null: inspect the job for status. See Jobs.

MCP application envelope

The SDK JSON-RPC result retains its content array. Its text item contains JSON:

{ "ok": false, "error": { "code": "NOT_FOUND", "message": "Resource not found." } }

Invocation failures set SDK isError: true. Successful calls use { "ok": true, "data": ... }. Fetching a failed job or returning mixed per-URL outcomes is a successful invocation. See MCP response shapes for each tool’s data value.

Unknown tools use NOT_FOUND; invalid tool arguments use VALIDATION_ERROR with a safe generic issue. Malformed protocol messages remain JSON-RPC invalid-request errors (-32600), and unknown protocol methods remain method-not-found (-32601). HTTP parsing and authentication occur before tool dispatch and use the HTTP errors above.

Public web tools

The anonymous tool page uses a separate operation outcome with remaining free runs: completed, failed, pending, or signup_required. Pending is HTTP 202 and retains jobIds; completed failures and the signup gate are HTTP 200 observations. Invocation failures use the structured error object, with remaining-run metadata under error.details when a run was spent. Captcha failures add the web-owned codes CAPTCHA_REQUIRED (400) and CAPTCHA_FAILED (403).

Contract change and rollout

This contract replaces string HTTP errors, key mutation receipts and unwrapped MCP application content directly. Clients must read error.code, consume returned safe key rows for rename/revoke, and unwrap MCP ok/data before reading results. No compatibility window or response alias is provided.

Clients should decode the current structured invocation errors and distinguish them from stored job failures. SDK JSON-RPC framing, scrape/analyse/map and job-read success values, and stored job diagnostics retain their documented shapes. Key rename/revoke return safe key rows.