Error Handling

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

Common Status Codes

Code	Description	Action
`200`	OK. The request was successful.	Process the response body.
`400`	Bad Request. Invalid parameters or malformed JSON.	Check your request payload and parameters.
`401`	Unauthorized. Missing or invalid API token.	Verify your `Authorization` header.
`404`	Not Found. The endpoint or resource does not exist.	Check the URL path.
`429`	Too Many Requests. Rate limit exceeded.	Implement backoff and retry (see Rate Limits).
`500`	Server Error. Internal system issue.	Retry the request later.
`503`	Service 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.

Deprecation Headers

Several legacy endpoints (e.g. /tasks/stt, /tasks/tts, /tasks/sunflower_inference) still work but are deprecated. When you call one, the API returns Deprecation and Sunset response headers indicating that the route will be removed in a future release.

Inspect these headers in your client and migrate to the unified endpoints — /tasks/audio/transcriptions, /tasks/audio/speech, and /tasks/chat/completions — before the sunset date.

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

Getting Started

Guides

Support

Common Status Codes

Timeouts

Deprecation Headers

Python Example

​Common Status Codes

​Timeouts

​Deprecation Headers

​Python Example

Common Status Codes

Timeouts

Deprecation Headers

Python Example