Error codes

The dataset and agent HTTP APIs return application errors in this JSON format. Use error.code to handle them in client code:

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

Payment responses from x402 can use a different body format. For a 402 payment challenge, read the PAYMENT-REQUIRED header. A subscription-related 402 instead uses error.code, such as SUBSCRIPTION_REQUIRED or QUOTA_EXHAUSTED, and does not ask for a wallet signature.

Public dataset queries

Subscription and agent APIs

These statuses apply to HTTP routes under /api/agent. With MCP, a billing failure inside a tool call sets isError: true and includes the error object in its text content; the HTTP response alone does not indicate tool success.

For SUBSCRIPTION_REQUIRED and QUOTA_EXHAUSTED from a subscription query, error.details includes the access quote and available payment options. No additional payment is made automatically. A 401 agent HTTP response includes an OAuth challenge in WWW-Authenticate.

Creator subscription settings

See Publish your first dataset for all publication requirements.

Notes for x402 agents

• Validation errors, missing datasets, dataset precondition failures, rate limits, and SEARCH_FAILED responses do not settle a payment.
• Send one request at a time with a given signed payment. Concurrent requests using it can receive PAYMENT_IN_FLIGHT. If the active request failed without settlement, its authorization remains unspent and can be retried while it is still valid. A successful payment cannot be reused.
• An initial 402 is the payment challenge. If a signed request also returns 402, check the current requirements, network, USDC balance, and authorization validity. See the FAQ.