Errors

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

Error response format

Error responses include an errors array with one or more normalized error objects:

{
  "errors": [
    {
      "code": "authentication_required",
      "message": "Authentication credentials were not provided",
      "field": null,
      "details": null
    }
  ]
}

Payment errors (402) use the same normalized envelope:

{
  "errors": [
    {
      "code": "insufficient_credits",
      "message": "Insufficient credits",
      "field": null,
      "details": null
    }
  ]
}

Validation errors may return multiple field-specific entries in errors:

{
  "errors": [
    {
      "code": "invalid_field",
      "message": "Input should be a valid URL, relative URL without a base",
      "field": "url",
      "details": null
    },
    {
      "code": "invalid_field",
      "message": "Scraper 'invalid' not found",
      "field": "scraper",
      "details": null
    }
  ]
}

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);
}