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

# Error handling

> Error payload shape and HTTP status codes returned by the v2 API

## Error payload

Every error response is a JSON object with an `error` field containing a typed error object:

```json theme={null}
{
  "error": {
    "type": "validation",
    "message": "Validation failed",
    "details": [
      {
        "code": "invalid_format",
        "format": "url",
        "path": ["url"],
        "message": "Invalid URL"
      }
    ]
  }
}
```

| Field | Description |
| - | - |
| `type` | Machine-readable error code (see table below). |
| `message` | Human-readable summary. |
| `details` | Optional array of field-level validation issues (present for `type: "validation"`). |

## Authentication errors

> [accordion] 401 — auth\_missing\_key
>
> ```json theme={null}
> {
>   "error": {
>     "type": "auth_missing_key",
>     "message": "API key required"
>   }
> }
> ```
>
> The `SGAI-APIKEY` header was not sent. Add it to every request.

> [accordion] 403 — auth\_invalid\_key
>
> ```json theme={null}
> {
>   "error": {
>     "type": "auth_invalid_key",
>     "message": "Invalid or deprecated API key"
>   }
> }
> ```
>
> The key was recognized as malformed, revoked, or issued against the legacy v1 surface. Rotate it from the [dashboard](https://scrapegraphai.com/dashboard).

## Validation errors (400)

Returned when the request body fails schema validation. The `details` array names each offending field.

```json theme={null}
{
  "error": {
    "type": "validation",
    "message": "Validation failed",
    "details": [
      {
        "code": "invalid_format",
        "format": "url",
        "path": ["url"],
        "message": "Invalid URL"
      },
      {
        "code": "custom",
        "path": ["url"],
        "message": "Private or internal URLs are not allowed"
      }
    ]
  }
}
```

Common `code` values: `invalid_format`, `invalid_type`, `too_small`, `too_big`, `invalid_value`, `custom`.

## Not found (404)

```json theme={null}
{
  "error": {
    "type": "not_found",
    "message": "Request not found"
  }
}
```

The resource ID is well-formed but does not exist for this account. Returned by lookup endpoints such as `GET /api/history/:id`, `GET /api/crawl/:id`, and `GET /api/monitor/:cronId` when the UUID does not correspond to a record on your account.

## Quota and rate limit errors

> [accordion] 402 — insufficient\_credits
>
> ```json theme={null}
> {
>   "error": {
>     "type": "insufficient_credits",
>     "message": "Not enough credits to complete this request"
>   }
> }
> ```
>
> Top up or upgrade your plan. Check balance with `GET /api/credits`.

> [accordion] 429 — rate\_limited
>
> ```json theme={null}
> {
>   "error": {
>     "type": "rate_limited",
>     "message": "Too many requests"
>   }
> }
> ```
>
> Back off and retry with exponential delay. Per-minute request limits depend on your plan.

## Server errors (5xx)

```json theme={null}
{
  "error": {
    "type": "internal_error",
    "message": "An error occurred while processing your request"
  }
}
```

Transient — retry with exponential backoff. If errors persist, check the [status page](https://status.scrapegraphai.com) or contact support.

## Retry strategy

| Error | Retryable? | Recommended action |
| - | - | - |
| `validation` (400) | No | Fix the request body. |
| `not_found` (404) | No | Verify the ID is correct and belongs to this account. |
| `auth_missing_key` / `auth_invalid_key` (401/403) | No | Fix the header or rotate the key. |
| `insufficient_credits` (402) | No | Top up credits. |
| `rate_limited` (429) | Yes | Exponential backoff, honor any `Retry-After` header. |
| `internal_error` (5xx) | Yes | Exponential backoff; 3–5 attempts max. |

The [Python](https://docs.scrapegraphai.com/sdks/python.md) and [JavaScript](https://docs.scrapegraphai.com/sdks/javascript.md) SDKs implement retries and typed error classes out of the box.


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