Errors & Retries

Handle responses according to whether payment credentials were submitted. Free discovery requests can use ordinary retry policies. Paid requests require more care because repeating a request can create another charge.

Paid summary retry matrix

Status	Meaning	Charged?	Recommended action
`200`	Summary returned	Yes	Store and use the response; do not refetch automatically
`400`	Invalid query or parameters	No	Fix the request; do not retry unchanged
`401`	Invalid API key or session	No	Replace or verify the credential
`402`	Payment required	No	Inspect the price, then retry once through a payment-aware client
`403`	Insufficient API-key credits	No	Add credits, then retry intentionally
`404`	Publication, post, or curated result not found	No	Verify identifiers or choose another result
`500`	Unexpected server error	Depends on request stage	If payment was submitted, verify settlement before retrying
`502`	Payment verification or settlement failed	Potentially unknown	Check the wallet or receipt before retrying
`503`	Article summary is not ready	No	Retry later; no payment challenge is issued

Successful free search and publication-discovery requests also return 200, but they are not charged.

Never put a paid request behind automatic retry middleware. After an API key or payment credential has been sent, a timeout or lost response does not prove that no charge occurred.

Error bodies

Invalid search parameters return 400 with field-level details:

{
  "error": "Invalid search query.",
  "issues": {
    "formErrors": [],
    "fieldErrors": {
      "q": ["Query must be at least 2 characters."]
    }
  }
}

An invalid API key returns 401:

{
  "error": "Unauthorized: invalid API key"
}

Insufficient API-key credits return 403:

{
  "error": "Insufficient credits",
  "reason": "insufficient_credits"
}

A missing post returns 404:

{
  "error": "Post not found."
}

A summary that is still processing returns 503:

{
  "error": "Post summary is not ready yet.",
  "code": "summary_not_ready"
}

Safe retry patterns

Free discovery requests

For GET /api/v1/search and publication discovery routes, retry transient 500 responses with exponential backoff and jitter. Do not retry 400 or 404 responses without changing the request.

Summary not ready

For 503 summary_not_ready, wait before retrying. The response does not include a payment challenge, so no payment was attempted.

if (response.status === 503) {
  const error = await response.json();

  if (error.code === "summary_not_ready") {
    // Schedule a later attempt instead of retrying in a tight loop.
    return;
  }
}

Wallet payments

The normal wallet flow contains exactly one expected retry:

Send a plain request and receive 402.
Inspect and approve the challenge.
Retry through the x402 or MPP-aware client.
Store the successful response.

If step 3 times out or returns 502, inspect the wallet transaction or MPP receipt before making another paid request.

API-key payments

An API-key request checks available credits before debiting them. A 401 or 403 is safe to correct and retry. If the request times out after being sent, check account credit activity before repeating it because the debit and response may already have completed.

Preserve partial research

When an agent purchases several summaries, keep every successful response even if another request fails. Synthesize only from successful results, identify the sources that could not be retrieved, and retry failed paid requests only after confirming their settlement state.

Get Started

Concepts

Curated Endpoints

Errors & Retries

Paid summary retry matrix

Error bodies

Safe retry patterns

Free discovery requests

Summary not ready

Wallet payments

API-key payments

Preserve partial research

​Paid summary retry matrix

​Error bodies

​Safe retry patterns

​Free discovery requests

​Summary not ready

​Wallet payments

​API-key payments

​Preserve partial research

Paid summary retry matrix

Error bodies

Safe retry patterns

Free discovery requests

Summary not ready

Wallet payments

API-key payments

Preserve partial research