Error Codes

Understanding and handling API errors.

Error Response Format

All errors follow a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked",
    "details": {
      "request_id": "req_abc123"
    }
  }
}

HTTP Status Codes

Code	Status	Meaning
`200`	OK	Request succeeded
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key lacks permissions
`404`	Not Found	Endpoint or resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error (retry)
`503`	Service Unavailable	Temporary outage (retry)

Common Error Codes

Authentication Errors

`invalid_api_key`

The API key provided is invalid, expired, or has been revoked.

Solution: Check your API key in the dashboard and ensure it's correctly formatted.

`missing_api_key`

No API key was provided in the Authorization header.

Solution: Include your API key in the header: x-api-key: YOUR_KEY

Request Errors

`invalid_parameter`

One or more request parameters are invalid or missing.

Solution: Check the error details for which parameter is invalid and correct it.

`invalid_date_format`

Date parameters must be in YYYY-MM-DD format.

Solution: Format dates as YYYY-MM-DD (e.g., "2026-10-15").

`invalid_location`

The location provided could not be resolved or is not supported.

Solution: Use a more specific location (e.g., "San Francisco, CA" instead of just "SF").

Rate Limit Errors

`rate_limit_exceeded`

You've exceeded your monthly credit limit.

Solution: Upgrade your plan or wait until your billing cycle resets.

`concurrent_limit_exceeded`

You've exceeded your concurrent request limit.

Solution: Wait for existing requests to complete or upgrade your plan.

`per_second_limit_exceeded`

You're making requests too quickly.

Solution: Implement rate limiting in your client (add delays between requests).

Data Errors

`no_results_found`

No hotels or rates found for the given search criteria.

Note: This is a successful request (200 OK) with zero results, not an error. You are not charged.

`source_unavailable`

The requested data source is temporarily unavailable.

Note: You are not charged for failed requests. Retry after a brief delay.

Handling Errors

Python Example

import requests
import time

def handle_api_error(response):
    """Handle different API errors appropriately."""
    if response.status_code == 200:
        return response.json()
    
    error_data = response.json().get('error', {})
    error_code = error_data.get('code')
    
    if response.status_code == 401:
        # Authentication error - check API key
        raise ValueError(f"Invalid API key: {error_data['message']}")
    
    elif response.status_code == 400:
        # Bad request - fix parameters
        raise ValueError(f"Invalid request: {error_data['message']}")
    
    elif response.status_code == 429:
        if error_code == 'rate_limit_exceeded':
            # Monthly limit reached
            raise Exception("Monthly credit limit exceeded. Upgrade plan.")
        else:
            # Too many requests per second - wait and retry
            print("Rate limited. Waiting 2 seconds...")
            time.sleep(2)
            return None  # Signal to retry
    
    elif response.status_code in [500, 503]:
        # Server error - retry with backoff
        print("Server error. Retrying...")
        return None  # Signal to retry
    
    else:
        raise Exception(f"Unknown error: {error_data['message']}")

# Usage
response = requests.post(url, headers=headers, json=payload)
result = handle_api_error(response)
if result is None:
    # Retry the request
    time.sleep(2)
    response = requests.post(url, headers=headers, json=payload)
    result = handle_api_error(response)

Best Practices

Always check status codes before parsing JSON
Implement retry logic for 5xx errors with exponential backoff
Handle rate limits gracefully with delays or queues
Log request_id from error responses for debugging
Validate parameters before making requests to avoid 400 errors
Monitor error rates to detect issues early

💡 Need Help?

If you're seeing errors you don't understand, contact support@scrapercompany.com with the request_id from the error response.