Error Handling

Learn about the error handling mechanisms in the MrScraper API, including common error codes, response formats, and best practices for managing errors in your applications.

Overview

The MrScraper API will return a JSON object containing error details when a request fails. This object includes an error code, message, and additional information to help diagnose the issue.

This reference covers the most common errors. It is not exhaustive — an endpoint may occasionally return a transient error not listed here. When in doubt, inspect the message and error fields in the response body.

Error response format

When a request fails, the API returns a non-2xx HTTP status code and a JSON body with a consistent shape:

{
  "message": "Unauthorized access",
  "error": "Unauthorized"
}

Field	Type	Description
`message`	string	Human-readable description of what went wrong.
`error`	string	Short error type or category (e.g. `Unauthorized`, `Not Found`).

HTTP status codes

Status	Error	Cause	Solution	Retryable
`400`	`Bad Request`	The request payload is malformed or a required parameter is missing or in the wrong format.	Fix the payload per the endpoint reference (e.g. use the `yyyy-MM-dd HH:mm:ss` date format where required).	No
`401`	`Unauthorized`	The API token is missing or invalid.	Include a valid token in the `x-api-token` header. See Authentication.	No
`403`	`Forbidden`	The token is valid but does not have permission to access this resource or Token limit exceeded.	Verify your plan and that the token has access to the resource. Contact support if needed.	No
`404`	`Not Found`	The requested resource (e.g. a scraper or result) does not exist.	Check that the `scraperId` / `resultId` is correct and belongs to your account.	No
`422`	`Unprocessable Entity`	The request is well-formed but failed validation.	Review the `message` for the specific validation failure and correct the input.	No
`429`	`Too Many Requests`	You have exceeded your rate limit.	Back off and retry after a short delay. Honor the `Retry-After` header if present.	Yes, with backoff
`500`	Server errors	A temporary problem on MrScraper's side.	Retry with exponential backoff. If it persists, contact support.	Yes, with backoff

Common errors

400 — Bad Request

The request body could not be parsed, or a parameter is missing or incorrectly formatted.

{
  "message": "startDate is required and must be in `yyyy-MM-dd HH:mm:ss` format",
  "error": "Bad Request"
}

401 — Unauthorized

The x-api-token header is missing or the token is invalid.

{
  "message": "Unauthorized access",
  "error": "Unauthorized"
}

Ensure the token is included on every request:

x-api-token: MRSCRAPER_API_TOKEN

403 — Forbidden

The token is authenticated but lacks permission for the requested resource.

{
  "message": "You do not have permission to access this resource",
  "error": "Forbidden"
}

404 — Not Found

The referenced scraper, result, or other entity could not be found.

{
  "message": "Resource not found",
  "error": "Not Found"
}

422 — Unprocessable Entity

The request was understood but failed validation.

{
  "message": "Validation failed",
  "error": "Unprocessable Entity"
}

429 — Too Many Requests

You have exceeded your rate limit.

{
  "message": "Too many requests. Please try again later."
}

Error Handling

On this page