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

<AccordionGroup>
  <Accordion title="401 — auth_missing_key" icon="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>

  <Accordion title="403 — auth_invalid_key" icon="ban">
    ```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).
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="402 — insufficient_credits" icon="coins">
    ```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>

  <Accordion title="429 — rate_limited" icon="gauge-high">
    ```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.
  </Accordion>
</AccordionGroup>

## 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](/sdks/python) and [JavaScript](/sdks/javascript) SDKs implement retries and typed error classes out of the box.