Error Handling

The Social Scraper API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Code	Status	Description
`200`	OK	The request was successful
`400`	Bad Request	The request was malformed or missing required parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	The API key doesn't have permission for this resource
`404`	Not Found	The requested profile or resource doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end

Error Response Format

All error responses follow a consistent JSON structure:

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

Common Errors

Invalid Username

Returned when the username format is invalid or contains unsupported characters.

{
  "error": "bad_request",
  "message": "Invalid username format"
}

Status Code: 400 Bad Request

Profile Not Found

Returned when the requested profile doesn't exist or is not publicly accessible.

{
  "error": "not_found",
  "message": "Profile not found"
}

Status Code: 404 Not Found

Rate Limit Exceeded

Returned when you've made too many requests in a given time period.

{
  "error": "rate_limited",
  "message": "Too many requests. Please retry after 60 seconds."
}

Status Code: 429 Too Many Requests

Rate limit headers are included in every response to help you track your usage.

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

Profile Extraction Failed

Returned when the API was unable to extract profile data from the platform.

{
  "error": "extraction_failed",
  "message": "Failed to extract profile data from page"
}

Status Code: 500 Internal Server Error

Handling Errors in Code

JavaScript

async function getProfile(platform, username) {
  const response = await fetch(
    `https://api.your-domain.com/${platform}/profile/${username}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  if (!response.ok) {
    const error = await response.json();
    
    switch (response.status) {
      case 401:
        throw new Error('Invalid API key');
      case 404:
        throw new Error(`Profile "${username}" not found`);
      case 429:
        throw new Error('Rate limit exceeded, please retry later');
      default:
        throw new Error(error.message || 'An error occurred');
    }
  }

  return response.json();
}

Python

import requests

def get_profile(platform, username):
    response = requests.get(
        f'https://api.your-domain.com/{platform}/profile/{username}',
        headers={'Authorization': f'Bearer {api_key}'}
    )
    
    if response.status_code == 401:
        raise Exception('Invalid API key')
    elif response.status_code == 404:
        raise Exception(f'Profile "{username}" not found')
    elif response.status_code == 429:
        raise Exception('Rate limit exceeded, please retry later')
    elif not response.ok:
        error = response.json()
        raise Exception(error.get('message', 'An error occurred'))
    
    return response.json()

Best Practices

Always check status codes - Don't assume every response is successful
Implement retry logic - For rate limits (429) and server errors (5xx)
Log errors - Keep track of errors for debugging
Handle gracefully - Provide meaningful feedback to your users

Error Handling

On this page