> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dripstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors & Retries

> Handle Drip API errors without losing research context or creating unintended charges.

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", ... }`.

<Warning>
  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.
</Warning>

## 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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "error": "Unauthorized: API key not found. Create one at /connect/api 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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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.

```typescript theme={null}
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 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](/unlocks) and [credit activity](/credits#ledger) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.