Errors | ScrapeRouter

ScrapeRouter uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error from the provided information, and codes in the 5xx range indicate a server error.

HTTP status codes

Status	Description
`200`	Request succeeded
`201`	Resource created successfully
`400`	Bad request - invalid parameters or malformed JSON
`401`	Unauthorized - missing or invalid API key
`402`	Payment required - insufficient credits
`403`	Forbidden - insufficient permissions
`404`	Not found - the requested resource does not exist
`429`	Too many requests - concurrency or rate limit exceeded
`500`	Internal server error

Error response format

Error responses include a JSON body with details about the error:

{
  "detail": "Authentication credentials were not provided."
}

Payment errors (402) include an error code:

{
  "error": "Insufficient credits",
  "code": "insufficient_credits"
}

Validation errors return field-specific messages:

{
  "url": ["This field is required."],
  "scraper": ["Scraper 'invalid' not found"]
}

Handling errors

import requests

response = requests.post(
    "https://www.scraperouter.com/api/v1/scrape/",
    headers={"Authorization": "Api-Key {your_api_key}"},
    json={"url": "https://example.com", "scraper": "auto"},
)

if response.status_code == 200:
    data = response.json()
elif response.status_code == 429:
    print("Rate limited, retrying...")
else:
    print(f"Error {response.status_code}: {response.json()}")

const response = await fetch("https://www.scraperouter.com/api/v1/scrape/", {
  method: "POST",
  headers: {
    "Authorization": "Api-Key {your_api_key}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com", scraper: "auto" }),
});

if (response.ok) {
  const data = await response.json();
} else if (response.status === 429) {
  console.log("Rate limited, retrying...");
} else {
  const error = await response.json();
  console.error(`Error ${response.status}:`, error);
}