Search Errors

The Search API can return different error responses when a request cannot be completed.

The response format depends on the type of error. The OpenAPI defines SearchErrorResponse for Search-specific errors and ErrorResponse for other API errors.

Search Error Response

Search-specific errors use the following response structure:

{
  "error": "error_code",
  "message": "Human-readable error description",
  "details": {}
}

The error and message fields are required. The details field is optional and can contain additional error context.

Error Fields

The OpenAPI gives no_results and upstream_blocked as examples of the error field.

Search-Specific Errors

The Search endpoint documents two responses that use SearchErrorResponse.

422 — Unprocessable Entity

The Search endpoint can return 422 with a SearchErrorResponse.

422 Unprocessable Entity

This response uses the following structure:

{
  "error": "no_results",
  "message": "Human-readable error description",
  "details": {}
}

The OpenAPI does not define a fixed message or details structure for this response, so use the values returned by the API.

502 — Bad Gateway

The Search endpoint can return 502 with a SearchErrorResponse.

502 Bad Gateway

The response uses the same Search-specific error structure:

{
  "error": "upstream_blocked",
  "message": "Human-readable error description",
  "details": {}
}

The OpenAPI documents upstream_blocked as an example machine-readable error code.

Other Search API Errors

The Search endpoint also documents the following HTTP responses:

These responses and their associated schemas are defined on POST /v1/search in the OpenAPI specification.

Handle Errors in Your Application

Check the HTTP status code before processing a successful Search response.

For Search-specific errors, inspect the returned error, message, and details fields.

For example:

response = requests.post(
    "YOUR_SCRAPER_API_URL/v1/search",
    headers={
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "query": "web scraping best practice"
    }
)

if response.status_code == 200:
    data = response.json()
else:
    error = response.json()
    print(error)

The exact error fields available depend on the response documented for that HTTP status.

Search Error Summary

The Search endpoint documents these HTTP responses:

200  Successful Response
401  Unauthorized
402  Insufficient token balance
408  Request timed out
422  Unprocessable Entity
429  Request throttled
500  Internal server error
502  Bad Gateway
503  Service temporarily unavailable

The 422 and 502 responses use SearchErrorResponse. The other documented error responses use ErrorResponse, except 429, for which the OpenAPI does not specify a response schema.

What's Next?

You now know the error responses documented for the Search API.

For the complete request and response definitions, see the Search API Reference.