Errors & Retries

Handle responses according to the resource and payment method. Free discovery requests can use ordinary retry policies. Individual posts have lifetime unlocks; paid stock-picks bundles are charged per request.

Paid summary retry matrix

Status	Meaning	Charged?	Recommended action
`200`	Summary returned	First unlock only	Store the response and any `unlockToken`; existing unlocks are free
`400`	Invalid query or parameters	No	Fix the request; do not retry unchanged
`401`	Invalid API key, OAuth token, or payment credential	No	Replace or verify the credential
`402`	Payment required	No	Inspect the price, then retry once through a payment-aware client
`403`	Insufficient credits or access denied	No	Inspect `reason` / `hint`; add credits or correct access
`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. A free post re-read returns unlocked: true and paymentInfo: { "protocol": "unlock", "amountUsd": "0.00", ... }.

Do not blindly retry wallet payments or paid stock-picks bundles. A timeout or lost response does not prove that no charge occurred. Use an existing post unlock when retrying a summary request.

Error bodies

Drip’s JSON errors include error (message), code, and hint. Validation errors can also include issues; credit errors can include reason. Payment-protocol challenges and failures may use the x402 or MPP response format instead, so inspect the HTTP status and payment headers as well. Invalid search parameters return 400 with field-level details:

{
  "error": "Invalid search query.",
  "code": "bad_request",
  "hint": "Check request parameters against /openapi.json.",
  "issues": {
    "formErrors": [],
    "fieldErrors": {
      "q": ["Query must be at least 2 characters."]
    }
  }
}

An invalid API key returns 401:

{
  "error": "Unauthorized: API key not found. Create one at /dashboard/api-keys or reconnect via mcp login.",
  "code": "unauthorized",
  "hint": "Send Authorization: Bearer pk_drip_… or an OAuth access token (mcp_at_…). See /llms.txt."
}

Insufficient API-key credits return 403:

{
  "error": "You're out of credits. Top up your balance to continue.",
  "code": "forbidden",
  "hint": "See /openapi.json for access requirements.",
  "reason": "insufficient_credits"
}

A missing post returns 404:

{
  "error": "Post not found.",
  "code": "not_found",
  "hint": "See /openapi.json or /llms.txt for available routes."
}

A summary that is still processing returns 503:

{
  "error": "Post summary is not ready yet.",
  "code": "summary_not_ready",
  "hint": "Retry later; the summary is still being generated."
}

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 and its unlockToken / X-Drip-Unlock header.

If step 3 times out or returns 502, inspect the wallet transaction or MPP receipt before making another paid request. For later reads of the same post, send X-Drip-Unlock with ordinary fetch. A valid token returns the current summary without charging. Treat a new 402 as a new payment decision.

API-key payments

An API-key post request checks for an existing user unlock before debiting credits. The first unlock and its debit are recorded together; retries for the same post and Drip account do not debit again. After a timeout, check unlocks and credit activity to determine whether the first request completed, then re-read using the same account. A 401 or an insufficient-credit 403 is safe to correct and retry. This post-unlock behavior does not apply to paid stock-picks bundles: each paid request can debit credits again. Stock Picks V2 subscription requests are covered by the plan and may return 429 when the API key reaches its allowance.

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

Topic Search

Entity Search

Company Lookup

Publications

Top-selling

Stock Picks

Curated Endpoints

Account

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