Error Codes

Understand and handle API error responses

HTTP Status Codes

400 Bad RequestClient Error

The request was malformed or contains invalid parameters.

Common causes:
  • Missing required fields
  • Invalid URL format
  • Unsupported parameter values
401 UnauthorizedAuth Error

Authentication failed or API key is missing.

Common causes:
  • Missing X-API-KEY header
  • Invalid or expired API key
  • Incorrect API key format
403 ForbiddenPermission Error

API key doesn't have permission for this operation.

Common causes:
  • Insufficient plan permissions
  • Restricted API endpoint
  • Account suspended
404 Not FoundResource Error

The requested resource doesn't exist.

Common causes:
  • Invalid job ID
  • Incorrect endpoint URL
  • Job has been deleted
429 Too Many RequestsRate Limit

Rate limit exceeded for your API key.

Response includes:
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Reset timestamp
  • Retry-After: Seconds to wait
500 Internal Server ErrorServer Error

An error occurred on our servers.

What to do:
  • Retry the request after a delay
  • Check our status page
  • Contact support if persists
503 Service UnavailableServer Error

Service temporarily unavailable.

Common causes:
  • Scheduled maintenance
  • Temporary system overload
  • Deploy in progress

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The 'target' parameter is required",
    "details": {
      "field": "target",
      "reason": "missing_required_field"
    }
  }
}

Handling Errors

error_handling.py
python
from scrapehub import ScrapeHubClient
from scrapehub.exceptions import (
    AuthenticationError,
    RateLimitError,
    InvalidRequestError,
    ScraperError
)

client = ScrapeHubClient(api_key="sk_live_xxxx_449x")

try:
    result = client.scrape("https://example.com")

except AuthenticationError as e:
    print(f"Auth error: {e}")
    # Check your API key

except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    print(f"Retry after: {e.retry_after} seconds")
    # Implement exponential backoff

except InvalidRequestError as e:
    print(f"Invalid request: {e}")
    print(f"Details: {e.details}")
    # Fix request parameters

except ScraperError as e:
    print(f"Scraper failed: {e}")
    # Handle scraper-specific errors

except Exception as e:
    print(f"Unexpected error: {e}")

Best Practices

  • Always implement proper error handling
  • Use exponential backoff for rate limit errors
  • Log errors for debugging
  • Monitor error rates in production
  • Handle network timeouts gracefully