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 
{
  "error": true,
  "message": "Missing required parameter: link",
  "code": 400
}

​
🐍 Python: Graceful Error Handling

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

def safe_request(url, headers):
    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.")
    elif response.status_code == 404:
        print("Resource not found or private.")
    else:
        print(f"Unexpected error {response.status_code}: {response.text}")
    
    return None

​
⏭ Next Steps

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