Error Handling

The Scrappa API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

All errors follow a consistent JSON structure:

{
  "message": "Error description",
  "error": "Optional error type"
}

HTTP Status Codes

Code	Meaning	Description
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthenticated	Missing or invalid API key
`403`	Forbidden	No active subscription or package, or out of credits
`404`	Not Found	Endpoint or resource not found
`422`	Validation Error	Request validation failed
`500`	Internal Server Error	Server error occurred
`502`	Bad Gateway	Invalid response from external service
`503`	Service Unavailable	Service temporarily unavailable

Common Error Examples

401 Unauthenticated

Missing or invalid API key

{
  "message": "Unauthenticated"
}

403 Forbidden

No active subscription or out of credits

422 Validation Error

Invalid request parameters

{
  "message": "Validation failed",
  "errors": {
    "q": ["The q field is required."],
    "location": ["The location must be a valid location."]
  }
}

500 Internal Server Error

Server error

{
  "error": "An error occurred while processing the request",
  "message": "Detailed error message"
}

Error Handling Best Practices

Always check the HTTP status code before processing the response
Implement retry logic for transient errors (500, 502, 503)
Use exponential backoff when retrying requests
Log error responses for debugging and monitoring
Display user-friendly error messages based on the error type
Handle validation errors (422) by showing specific field errors to users
For 401/403 errors, prompt users to check their API key or subscription status

Example Error Handling

async function handleApiRequest(url, apiKey) {
  try {
    const response = await fetch(url, {
      headers: {
        'X-API-KEY': apiKey
      }
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 401:
          throw new Error('Invalid API key. Please check your credentials.');
        case 403:
          throw new Error('Access denied. Please check your subscription.');
        case 422:
          const validationErrors = error.errors || {};
          throw new Error(`Validation failed: ${JSON.stringify(validationErrors)}`);
        default:
          throw new Error(error.message || 'An error occurred');
      }
    }
    
    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}