Error handling

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"
      }
    ]
  }
}

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

401 — auth_missing_key

{
  "error": {
    "type": "auth_missing_key",
    "message": "API key required"
  }
}

The SGAI-APIKEY header was not sent. Add it to every request.

403 — auth_invalid_key

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

402 — insufficient_credits

{
  "error": {
    "type": "insufficient_credits",
    "message": "Not enough credits to complete this request"
  }
}

Top up or upgrade your plan. Check balance with GET /api/credits.

429 — rate_limited

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

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 and JavaScript SDKs implement retries and typed error classes out of the box.

API Documentation

Scrape

Extract

Search

Crawl

Monitor

History

Account

Error payload

Authentication errors

Validation errors (400)

Not found (404)

Quota and rate limit errors

Server errors (5xx)

Retry strategy

​Error payload

​Authentication errors

​Validation errors (400)

​Not found (404)

​Quota and rate limit errors

​Server errors (5xx)

​Retry strategy

Error payload

Authentication errors

Validation errors (400)

Not found (404)

Quota and rate limit errors

Server errors (5xx)

Retry strategy