Error Handling

Spidra returns consistent error responses using standard HTTP status codes and descriptive messages. If something goes wrong with your request—like invalid input, missing authentication, or rate limits—you’ll receive a clear JSON error object.

Error Response Format

{
	"status": "error",
	"message": "Detailed error explanation"
}

Common Error Codes

Status Code	Description
400 Bad Request	The request conflicts with the current state (e.g. cancelling an already-finished job, retrying a batch with no failed items).
401 Unauthorized	Authentication failed — missing, invalid, or disabled API key.
402 Payment Required	Your subscription payment is overdue. See `PAYMENT_OVERDUE` below.
403 Forbidden	Your key is valid but not permitted — usually the monthly credit limit has been reached.
404 Not Found	The requested resource does not exist.
422 Unprocessable Entity	The request body failed validation. The response includes an `errors` array listing each problem.
429 Too Many Requests	You have exceeded a rate limit. See the `code` field for which one.
503 Service Unavailable	The service is temporarily at capacity. Retry after the `retry_after` value (seconds).
500 Internal Server Error	An unexpected error occurred on the server.

Validation Errors (422)

All request-body validation failures on submit endpoints return 422 with an errors array — one entry per problem — alongside the usual message:

{
  "status": "error",
  "message": "Request validation failed. Fix the errors below and try again.",
  "errors": [
    "urls[0] (forEach): requires an \"observe\" field describing which elements to find",
    "urls[1]: not a valid URL"
  ]
}

Error Codes

Some errors include a code field with a machine-readable identifier:

Code	Status	Meaning
`TOO_MANY_PENDING_JOBS`	429	You have too many jobs currently queued. Wait for some to complete before submitting more.
`SERVICE_BUSY`	503	The server queue is at capacity across all users. Retry after `retry_after` seconds.
`PAYMENT_OVERDUE`	402	Your payment is overdue. Update your payment method to continue.

{
  "status": "error",
  "message": "The scraping service is currently at capacity. Please retry in a few minutes.",
  "code": "SERVICE_BUSY",
  "retry_after": 60
}

Using the API

Scrape Endpoints

Logs

Crawl Endpoints

Account

Error Handling

Error Response Format

Common Error Codes

Validation Errors (422)

Error Codes

​Error Response Format

​Common Error Codes

​Validation Errors (422)

​Error Codes

Error Response Format

Common Error Codes

Validation Errors (422)

Error Codes