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

# Troubleshooting

> Read the status and code, retry only rate limits and outages, honor Retry-After, back off, and let the SDK retry for you.

A failed call costs nothing. Keep the HTTP status, `code` and `requestId` of a failure. If your client timed out, check the original request before you retry because it may still finish. Every code and its fix is in [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Start with the status

| Status | Check |
| - | - |
| `200` with less than you expected | A `warning`, `isTruncated`, a filter that matched nothing, or an empty page. See [Scrape](https://docs.stophy.dev/scrape/overview#timeouts-warnings-and-errors). |
| `400` | `error` names the field the endpoint does not take or the value it rejects. |
| `401` | No key, a wrong or expired key, or a field that needs a key. See [Get credentials](https://docs.stophy.dev/get-credentials.md). |
| `402` | Balance too low. See [Pricing](https://docs.stophy.dev/account/pricing.md). |
| `403`, `404`, `405`, `409` | Read `code` in [Errors](https://docs.stophy.dev/api-reference/errors.md). |
| `413`, `415` | Body too large, or not JSON. |
| `429` | A limit. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md). |
| `500` to `504` | Stophy or the site is not answering. Retry. |

## Retry

Retry a call only when `retryable` is `true`. If it is missing, retry only `429`, `500`, `502`, `503` and `504`.

1. Wait `retryAfterSeconds` when it is present. Otherwise wait 0.5 seconds, then double the wait for each retry. Add random jitter so workers do not retry together.
2. Stop after 3 retries, or when the wait is over 60 seconds. A `freeLimit` wait can be hours, so get a key instead.
3. Log `requestId` on the last error.

The [SDKs](https://docs.stophy.dev/sdks.md) do this. They follow `retryable`, retry eligible network errors, and stop after `maxRetries` retries (2 by default) or a wait over 60 seconds. A write that may have run is retried only when it can be replayed safely. API errors carry `code`, `retryable` and the request ID.

```ts theme={null}
import { Stophy, StophyError } from "stophy";

const stophy = new Stophy({ maxRetries: 3 });

try {
  const page = await stophy.scrape({ url: "https://bun.com/docs/runtime/bunfig" });
  console.log(page.data.metadata.title);
} catch (error) {
  if (error instanceof StophyError) console.log(`${error.code} (${error.requestId})`);
}
```

Python: `Stophy(max_retries=3)`, and catch `StophyError` with `error.code` and `error.request_id`.

## Report a problem

If an answer is wrong or differs from these docs, send [feedback](https://docs.stophy.dev/production/agent-feedback.md) with the `X-Request-ID`. For support, email [support@stophy.dev](mailto:support@stophy.dev) with it. [`GET /v1/logs/{id}`](https://docs.stophy.dev/account/usage#list-calls) shows what a request cost.


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