Skip to main content
If a request fails, Sorsa API returns a standard HTTP error code. This page helps you understand what went wrong and how to fix it.

​
📊 Quick Reference Table

CodeTypeMeaningAction Required
200SuccessOKNo action needed.
400Client ErrorBad RequestCheck your parameters.
401Client ErrorUnauthorizedCheck your ApiKey header and value.
403Client ErrorForbiddenNo credits left or key deleted.
404Client ErrorNot FoundUser/Tweet doesn’t exist or is private.
429Client ErrorToo Many RequestsYou exceeded 20 req/s. Slow down.
500Server ErrorInternal ErrorSomething broke on our side.

​
🛠 Deep Dive & Solutions

​
400 Bad Request

The server cannot process the request due to something that is perceived to be a client error.
  • Common cause: You missed a required parameter like link, id, or query.
  • Fix: Double-check the API Reference for that specific endpoint.

​
401 Unauthorized

Authentication failed.
  • Common cause: Missing ApiKey header or the key is misspelled.
  • Fix: Ensure your header is exactly ApiKey (case-sensitive) and your key is active in the Dashboard.

​
403 Forbidden

Your key is valid, but the action is not allowed.
  • Common cause: You have 0 credits remaining on your balance.
  • Fix: Check your usage at GET /key-usage-info or top up your account.

​
404 Not Found

The requested resource does not exist.
  • Common cause: The X user has changed their handle, deleted their account, or the tweet was removed.
  • Note: Also happens if the account is Private (Protected) — we can only access public data.

​
429 Too Many Requests

You hit the rate limit.
  • Condition: More than 20 requests in 1 second.
  • Fix: Implement a small delay (time.sleep(0.05)) in your loop. See Rate Limits for more.

​
🪵 Standard Error Response

When an error occurs, the API returns a JSON body to help you debug: JSON 
{
  "message": "ApiKey required"
}

​
🐍 Python: Error Handling

Don’t let your script crash. Use a try-except block to handle different status codes. Python 
import requests
import time

def safe_request(url, headers):
    try:
        response = requests.get(url, headers=headers)
       
        if response.status_code == 200:
            return response.json()
       
        elif response.status_code == 401:
            print("Critical: Check your API Key!")
        elif response.status_code == 403:
            print("Out of credits! Visit dashboard to top up.")
        elif response.status_code == 429:
            print("Throttling... slowing down.")
            time.sleep(1)
        elif response.status_code == 404:
            print("Resource not found or private.")
        else:
            print(f"Unexpected error {response.status_code}: {response.text}")
       
        return None
    except Exception as e:
        print(f"Request error: {e}")
        return None

​
JavaScript: Error Handling

async function safeRequest(url, headers) {
  try {
    const response = await fetch(url, { headers });
    
    if (response.status === 200) {
      return await response.json();
    }
    
    if (response.status === 401) {
      console.log("Critical: Check your API Key!");
    } else if (response.status === 403) {
      console.log("Out of credits! Visit dashboard to top up.");
    } else if (response.status === 429) {
      console.log("Throttling... slowing down.");
      await new Promise(r => setTimeout(r, 1000));
    } else if (response.status === 404) {
      console.log("Resource not found or private.");
    } else {
      const text = await response.text();
      console.log(`Unexpected error ${response.status}: ${text}`);
    }
    
    return null;
  } catch (error) {
    console.log(`Request error: ${error.message}`);
    return null;
  }
}

​
⏭ Next Steps

  • Response Format — Understanding the structure of successful responses.
  • Pagination — How to avoid errors while fetching large lists.