Skip to main content
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.
StatusMeaningCharged?Recommended action
200Summary returnedYesStore and use the response; do not refetch automatically
400Invalid query or parametersNoFix the request; do not retry unchanged
401Invalid API key or sessionNoReplace or verify the credential
402Payment requiredNoInspect the price, then retry once through a payment-aware client
403Insufficient API-key creditsNoAdd credits, then retry intentionally
404Publication, post, or curated result not foundNoVerify identifiers or choose another result
500Unexpected server errorDepends on request stageIf payment was submitted, verify settlement before retrying
502Payment verification or settlement failedPotentially unknownCheck the wallet or receipt before retrying
503Article summary is not readyNoRetry 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:
  1. Send a plain request and receive 402.
  2. Inspect and approve the challenge.
  3. Retry through the x402 or MPP-aware client.
  4. 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.