Skip to main content

​
API Error Codes: Troubleshooting 400, 401, 403, 429, and 500 Responses

When a request fails, Sorsa API returns a standard HTTP status code and a JSON body with a message field describing the problem. This page covers every error code you may encounter, what causes it, and how to resolve it.

​
Error response format

All error responses follow the same structure: 
{
  "message": "ApiKey required"
}
The message field contains a human-readable description of the error. Always check this field first when debugging - it often points directly to the problem.

​
Quick reference

CodeTypeMeaning
200SuccessRequest completed successfully
400Client errorBad request - invalid or missing parameters
401Client errorUnauthorized - authentication failed
403Client errorForbidden - valid key but no access or credits
404Client errorNot found - resource does not exist or is private
429Client errorToo many requests - rate limit exceeded
500Server errorInternal error - something went wrong on our side

​
400 Bad Request

The request could not be processed because of invalid or missing parameters. Common causes:
  • A required parameter is missing (for example, link, id, username, or query)
  • A parameter value has the wrong type or format (for example, passing a string where a number is expected)
  • The JSON body in a POST request is malformed or empty
How to fix: Check the API Reference for the specific endpoint you are calling. Verify that all required parameters are present and correctly formatted. For POST requests, make sure your Content-Type is set to application/json and the body is valid JSON.

​
401 Unauthorized

Authentication failed. The API could not identify your account. Common causes:
  • The ApiKey header is missing entirely
  • The header name is misspelled (it is case-sensitive - ApiKey, not Api-Key, apikey, or api_key)
  • The API key value is incorrect, was copied with extra whitespace, or belongs to a deleted key
How to fix: Verify that your request includes the header exactly as ApiKey: your_key_here. Check that the key is still active in your Dashboard. If in doubt, copy the key directly from the dashboard and paste it into your code. For more details, see Authentication.

​
403 Forbidden

Your API key is valid, but the request was rejected. Common causes:
  • Your request quota is exhausted (0 requests remaining)
  • Your subscription has expired
How to fix: Check your remaining balance by calling GET /key-usage-info or by visiting your Dashboard. If your requests are depleted, top up your account or upgrade your plan on the Billing page.

​
404 Not Found

The requested resource does not exist. Common causes:
  • The X user has changed their username, deleted their account, or been suspended
  • The tweet has been deleted by the author
  • The account or tweet is private (protected) - Sorsa API can only access public data
  • The endpoint URL itself is incorrect
How to fix: Verify that the user or tweet you are requesting still exists and is publicly accessible on X. If you are using a user ID, confirm it has not been reassigned. If you are using a username, the user may have changed it - use /username-to-id to resolve the current mapping.

​
429 Too Many Requests

You have exceeded the rate limit of 20 requests per second. Common causes:
  • Sending requests in a tight loop without any delay
  • Running multiple parallel workers that share the same API key
How to fix: Add a small delay between requests (50ms is enough to stay safely under the limit) or implement retry logic with a 1-second pause. See Rate Limits for detailed strategies and code examples.

​
500 Internal Server Error

Something went wrong on our side. What to do:
  • Retry the request after a short delay (1-2 seconds). Transient 500 errors often resolve themselves.
  • If the error persists across multiple retries or affects multiple endpoints, check the Sorsa Status Page for ongoing incidents.
  • If the problem continues, contact support at [email protected] or on Discord with the endpoint URL, request body, and approximate timestamp.

​
Handling errors in code

A resilient integration should handle all error codes gracefully instead of crashing on unexpected responses. Here is a reusable pattern for both Python and JavaScript. Python 
import time
import requests

def sorsa_request(method, endpoint, api_key, params=None, json_body=None, max_retries=3):
    url = f"https://api.sorsa.io/v3{endpoint}"
    headers = {"ApiKey": api_key}

    for attempt in range(max_retries):
        if method == "GET":
            response = requests.get(url, headers=headers, params=params)
        else:
            response = requests.post(url, headers=headers, json=json_body)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            time.sleep(1)
            continue

        if response.status_code == 500:
            time.sleep(2)
            continue

        # Non-retryable errors: 400, 401, 403, 404
        error_msg = response.json().get("message", "Unknown error")
        raise Exception(f"{response.status_code}: {error_msg}")

    raise Exception("Max retries exceeded")


# Usage
data = sorsa_request("GET", "/info", "YOUR_API_KEY", params={"username": "elonmusk"})
print(data["display_name"])
JavaScript 
async function sorsaRequest(method, endpoint, apiKey, body = null, maxRetries = 3) {
  const url = `https://api.sorsa.io/v3${endpoint}`;
  const options = {
    method,
    headers: { "ApiKey": apiKey }
  };

  if (body) {
    options.headers["Content-Type"] = "application/json";
    options.body = JSON.stringify(body);
  }

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 200) {
      return await response.json();
    }

    if (response.status === 429) {
      await new Promise(r => setTimeout(r, 1000));
      continue;
    }

    if (response.status === 500) {
      await new Promise(r => setTimeout(r, 2000));
      continue;
    }

    // Non-retryable errors: 400, 401, 403, 404
    const data = await response.json();
    throw new Error(`${response.status}: ${data.message || "Unknown error"}`);
  }

  throw new Error("Max retries exceeded");
}

// Usage
const data = await sorsaRequest("GET", "/info?username=elonmusk", "YOUR_API_KEY");
console.log(data.display_name);
The key idea: retry on 429 and 500 (these are transient), but fail immediately on 400, 401, 403, and 404 (these require a code or configuration fix).

​
Next steps

  • Rate Limits - Detailed strategies for staying within the 20 req/s limit
  • Pagination - How to fetch large datasets without errors
  • API Reference - Full endpoint list with parameter schemas