Error codes

quarry's errors share one format. Handle them by error.code; the message is for people and can change:

{
  "error": {
    "code": "QUERY_TOO_LONG",
    "message": "'query' too long (max 2000 chars)",
    "details": { "field": "query", "max": 2000 }
  }
}

details is optional. Over HTTP, the error comes with the status below. Over MCP, it's the text of a tool result with isError: true, and the HTTP status is 200. Two exceptions: MCP arguments outside the documented limits get plain text starting with MCP error -32602, not JSON, and the x402 402 responses below have their own format.

Dataset routes

GET and POST on /{username}/{slug}:

Payment responses

A paid POST can answer 402 in three ways. Read the headers, not only the body:

The body of the first 402, before any payment:

{
  "error": "payment_required",
  "hint": "Payment requirements are in the PAYMENT-REQUIRED response header (base64 JSON). …",
  "contract": "https://quarry.market/alice/market-outlook",
  "terms": "https://quarry.market/terms"
}

Neither refusal charges you, and the signed payment stays unspent. The x402 library behind the route can also answer 502 or 500 with { "error": "…" } when the facilitator fails: retry after a delay.

When a payment keeps failing

• Network: sign for the network in accepts. A payment for Base can't pay on Base Sepolia, or the reverse.
• Balance: the wallet needs at least amount of the USDC contract in accepts. An unfunded wallet is refused at verification, and error names the balance or a reverted transfer.
• Freshness: sign a new payment for each question. A payment that already settled, or has expired, is refused.
• Price: if the price changed, sign for the requirements of the latest 402.
• Format: sign the payment the x402 client makes for an exact USDC requirement, an EIP-3009 authorization. Other formats, such as Permit2, are refused at verification with unsupported_payment_payload.
• Spend cap: the x402 client refuses to sign over $1 by default: see Paying with x402.

Subscription and agent APIs

The routes under /api/agent, and query_dataset on the sign-in address. ask uses the same codes, except that a used-up month falls back to a payment request instead of QUOTA_EXHAUSTED:

For SUBSCRIPTION_REQUIRED and QUOTA_EXHAUSTED on POST /api/agent/query, details holds the quote_access result with the other ways to pay. Nothing is ever bought for you.

MCP tool results

Tool errors come as isError: true with the format above. Besides the subscription codes, ask and the other tools can return:

An ask without payment isn't an error code: it's the PaymentRequired result described in the MCP server reference.