> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dripstack.xyz/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 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.

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

## Error bodies

Invalid search parameters return `400` with field-level details:

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

An invalid API key returns `401`:

```json theme={null}
{
  "error": "Unauthorized: invalid API key"
}
```

Insufficient API-key credits return `403`:

```json theme={null}
{
  "error": "Insufficient credits",
  "reason": "insufficient_credits"
}
```

A missing post returns `404`:

```json theme={null}
{
  "error": "Post not found."
}
```

A summary that is still processing returns `503`:

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

```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.

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.