Add MCP to your AI agentCreate accountStart for free
Introduction

API Status Codes

ScrapeRing processes scraping requests asynchronously. Creating a task returns its id right away; you then request the result with that id until the task is finished. Credits are charged only for successful tasks — if a task fails, its credits are returned to your balance.

HTTP status codes

Every API response has an HTTP status code. 200 means the request was accepted. Any other code means the request was not accepted: the task wasn't created or wasn't found.

CodeDetailsWhat to do
200The request was accepted. Check the task status in the status field — see Task statuses—
400The request body or parameters are invalidFix the request and send it again
401The API key is missing, invalid or disabledCheck the Authorization: Bearer YOUR_API_KEY header and the key in the dashboard
402Not enough credits, or your credits have expiredTop up your balance or renew your plan
403The API key has no access to this scraperAllow the scraper for this key in the dashboard
404The scraper or the task with this id was not foundCheck the endpoint path and the task id
409The task could not be created because of a conflicting requestSend the request again
429Too many requests, or the key's daily or monthly limit is reachedWait until the time in the X-RateLimit-Reset header and send the request again
500An error on our sideRepeat the request later
503The service is temporarily busyRepeat the request after the number of seconds in the Retry-After header

Error response body

If the request was not accepted, the response body contains an error field with a short description:

{
  "error": "Insufficient credits"
}

For 400, the response also contains a details field that lists the rejected request fields:

{
  "error": "Validation failed",
  "details": {
    "url": ["Invalid URL"]
  }
}

Some errors also contain a code field. When the key has no access to the scraper, 403 returns API_KEY_SCOPE_DENIED and the missing scope:

{
  "error": "this key has no access to scope \"url\"",
  "code": "API_KEY_SCOPE_DENIED",
  "scope": "url"
}

A busy service returns 503 with "code": "SERVICE_BUSY".

Task statuses

The result endpoint (GET /api/parsing/v1/result/{scraper}/{requestId}) returns the task status in the status field. The statuses are the same for every scraper.

StatusDetails
queuedThe task has been created and is waiting in the queue. The request that creates a task returns this status too
parsingThe task is being processed
readyThe task is finished. Whether it succeeded is shown in data — see below
cancelledThe task was cancelled from the dashboard

While the status is queued or parsing, repeat the request a few seconds later. ready and cancelled are final.

If a task gets no result within 3 hours, it is finished as failed: the status becomes ready, data.success is false and data.error is "Parsing request timed out after three hours". Its credits are returned to your balance.

Checking whether a task succeeded

ready means the task is finished, not that it succeeded. How a failed task looks depends on the scraper:

ScraperTask failed whenResults are in
URL Scraperdata.success is false, the reason is in data.errordata
Google SERP, Yandex SERPdata.error is presentdata
Google News, Google Trends, MSN, Opera News, Galaxy Store Reviewsdata.success is false, the reason is in data.errordata.data

For the URL Scraper, data.error is a short error code such as SYSTEM_ERR or NOT_ENOUGH_HTML_ERR, and data.errorFull has the details when available. A failed task may still contain the page content that was loaded. For the other scrapers, a failed task has no data.data.

URL Scraper — failed task:

{
  "status": "ready",
  "requestId": "5cfce409-1a30-4181-88eb-75b995499cd0",
  "data": {
    "url": "https://nonexistent-domain.example",
    "time": "0.77",
    "content": "",
    "success": false,
    "error": "SYSTEM_ERR",
    "errorFull": "unknown error: net::ERR_NAME_NOT_RESOLVED"
  },
  "respondedAt": "2026-01-01T00:00:03.240Z"
}

Google SERP, Yandex SERP — a task that timed out. Other failed SERP tasks have only data.error, without data.success:

{
  "status": "ready",
  "requestId": "abaf4ac3-d9e7-43f2-a414-e7d2ca9ff635",
  "data": {
    "success": false,
    "error": "Parsing request timed out after three hours"
  },
  "respondedAt": "2026-01-01T00:00:03.240Z"
}

Google News, Google Trends, MSN, Opera News, Galaxy Store Reviews — failed task:

{
  "status": "ready",
  "requestId": "8f2d1c6e-4b7a-4e3f-9a51-2c0d7e6b9f14",
  "data": {
    "success": false,
    "error": "[msn] HTTP 400"
  },
  "respondedAt": "2026-01-01T00:00:03.240Z"
}

If a request fails

Next steps