Skip to main content

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 payload

Every error response is a JSON object with an error field containing a typed error object: 
{
  "error": {
    "type": "validation",
    "message": "Validation failed",
    "details": [
      {
        "code": "invalid_format",
        "format": "url",
        "path": ["url"],
        "message": "Invalid URL"
      }
    ]
  }
}
FieldDescription
typeMachine-readable error code (see table below).
messageHuman-readable summary.
detailsOptional array of field-level validation issues (present for type: "validation").

​
Authentication errors

{
  "error": {
    "type": "auth_missing_key",
    "message": "API key required"
  }
}
The SGAI-APIKEY header was not sent. Add it to every request.
{
  "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.

​
Validation errors (400)

Returned when the request body fails schema validation. The details array names each offending field. 
{
  "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)

{
  "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

{
  "error": {
    "type": "insufficient_credits",
    "message": "Not enough credits to complete this request"
  }
}
Top up or upgrade your plan. Check balance with GET /api/credits.
{
  "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)

{
  "error": {
    "type": "internal_error",
    "message": "An error occurred while processing your request"
  }
}
Transient — retry with exponential backoff. If errors persist, check the status page or contact support.

​
Retry strategy

ErrorRetryable?Recommended action
validation (400)NoFix the request body.
not_found (404)NoVerify the ID is correct and belongs to this account.
auth_missing_key / auth_invalid_key (401/403)NoFix the header or rotate the key.
insufficient_credits (402)NoTop up credits.
rate_limited (429)YesExponential backoff, honor any Retry-After header.
internal_error (5xx)YesExponential backoff; 3–5 attempts max.
The Python and JavaScript SDKs implement retries and typed error classes out of the box.