Skip to main content
The Sunbird AI API uses standard HTTP status codes to indicate the success or failure of requests.

​
Common Status Codes

CodeDescriptionAction
200OK. The request was successful.Process the response body.
400Bad Request. Invalid parameters or malformed JSON.Check your request payload and parameters.
401Unauthorized. Missing or invalid API token.Verify your Authorization header.
404Not Found. The endpoint or resource does not exist.Check the URL path.
429Too Many Requests. Rate limit exceeded.Implement backoff and retry (see Rate Limits).
500Server Error. Internal system issue.Retry the request later.
503Service Unavailable. Model is loading or overloaded.Retry with exponential backoff.

​
Timeouts

Some AI models, particularly large ones like Sunflower or Whisper, may take time to process requests. Server-side timeouts (e.g., 408, 504) can occur if the request takes too long.
For large operations (like long audio files), consider using the asynchronous workflows or signed URL upload methods where available to avoid timeouts.

​
Python Example

Here is a robust way to handle errors in Python: 
import requests
import time

def call_api_robustly(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)
        
        if response.status_code == 200:
            return response.json()
            
        if response.status_code in [429, 503]:
            wait_time = (2 ** attempt)  # Exponential backoff
            print(f"Rate limited. Retrying in {wait_time}s...")
            time.sleep(wait_time)
            continue
            
        # Non-retryable error
        print(f"Error {response.status_code}: {response.text}")
        break
        
    return None