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

# Errors

> The error response shape, every status code, and the full error code reference.

Every failed response has `"success": false`. What's under `error` takes one of two shapes, depending on where the request failed.

## Platform-level errors

Failures in authentication, credits, rate limiting, or an unrecognized route come from shared middleware that runs before any tool-specific code, and return a structured object with a stable `code` you can match on in your own error handling:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request. Buy a top-up pack or wait for your cycle to renew."
  }
}
```

<ResponseField name="error.code" type="string">
  A stable, machine-readable identifier. Safe to switch on.
</ResponseField>

<ResponseField name="error.message" type="string">
  A human-readable explanation. Safe to show a user, not guaranteed to stay word-for-word identical between API versions.
</ResponseField>

## Endpoint-level errors

Validation and execution failures inside an individual tool (a missing `url`, an unreachable target, a malformed upload) return `error` as a **plain string** instead:

```json theme={null}
{
  "success": false,
  "error": "The `url` query parameter is required"
}
```

<Warning>
  Check the type of `error` before reading it: `typeof error === "object"` means a stable `code` is available; `typeof error === "string"` means it's a message meant for a human, not for pattern matching. Both shapes always sit under the same `error` key.
</Warning>

## Status codes

| Status | Meaning                                                                                                      |
| ------ | ------------------------------------------------------------------------------------------------------------ |
| `200`  | Success (or, for `/broken-links/crawl` and `/link-extract/crawl` status polling, a job that's still running) |
| `202`  | A crawl job was accepted and queued — response includes a `jobId`                                            |
| `400`  | Bad request — missing or invalid parameters, or a target URL that can't be processed                         |
| `401`  | Missing, malformed, or revoked API key                                                                       |
| `402`  | Signed-in balance doesn't cover this request's credit cost                                                   |
| `404`  | Unknown `/v1` route, or a job/file that doesn't exist or has expired                                         |
| `408`  | The target page took too long to load (render endpoints only)                                                |
| `429`  | Per-minute rate limit exceeded, or the anonymous daily allowance is used up                                  |
| `500`  | Unexpected server-side failure                                                                               |

## Error code reference

| Status | Code                   | When it happens                                                                                                                         |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | *(string message)*     | Missing/invalid input — e.g. no `url`, an unsupported `format`, an unparseable target URL                                               |
| `401`  | `invalid_api_key`      | The API key is malformed, unknown, or revoked                                                                                           |
| `401`  | `unauthorized`         | An account-only route was called without a valid session or key                                                                         |
| `402`  | `insufficient_credits` | Your credit balance is below this request's cost. Response includes `creditsRequired`                                                   |
| `404`  | `unknown_endpoint`     | No route matches this method + path under `/v1`                                                                                         |
| `404`  | *(string message)*     | A crawl `jobId` or a generated file has expired or never existed                                                                        |
| `408`  | *(string message)*     | `/url-to-pdf` or `/screenshot` timed out waiting for the target page to render                                                          |
| `429`  | `rate_limited`         | You exceeded your plan's requests-per-minute limit                                                                                      |
| `429`  | `free_quota_exhausted` | An anonymous caller used up the 10-credit daily allowance for their IP                                                                  |
| `500`  | `caller_unresolved`    | Internal wiring error — not something a valid request should trigger. [Contact support](mailto:support@pocketutils.com) if you see this |
| `500`  | *(string message)*     | An unexpected failure while processing the request                                                                                      |

## Retrying

| Status                     | Retryable?                                                                                            |
| -------------------------- | ----------------------------------------------------------------------------------------------------- |
| `400`, `401`, `402`, `404` | No — fix the request, credential, or balance first                                                    |
| `408`                      | Yes — often transient on a slow target page                                                           |
| `429`                      | Yes, after backing off. Honor the `RateLimit-Reset` header (seconds) rather than retrying immediately |
| `500`                      | Yes, with backoff — these are unexpected                                                              |

<Note>
  Calling through the website's own proxy at `pocketutils.com/api/v1` (instead of `api.pocketutils.com` directly) adds one more possible failure: a `502` with `{ "success": false, "error": "Proxy Service Error", "message": "...", "details": "..." }` if the proxy itself can't reach the API. Direct integrations against `api.pocketutils.com` never see this shape.
</Note>

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Avoid `401` errors before they happen.
  </Card>

  <Card title="Rate Limits & Credits" icon="gauge-high" href="/rate-limits-and-credits">
    Avoid `429` and `402` errors before they happen.
  </Card>
</CardGroup>


## Related topics

- [Down Checker](/api-reference/down-check.md)
- [Meta Scanner](/api-reference/meta-scan.md)
- [SSL Scanner](/api-reference/ssl-scan.md)
- [Broken Link Checker](/api-reference/broken-links.md)
- [Screenshot](/api-reference/screenshot.md)