Troubleshooting OpenAI SDK Timeouts with Fikra API

When integrating the OpenAI SDK with Fikra API, timeouts can occur due to network latency, rate limiting, or upstream availability. This guide explains how to handle common HTTP status codes and implement robust retry logic.

Understanding HTTP Status Codes

Fikra API returns standard HTTP status codes to indicate request outcomes:

• 400 Bad Request: The request is malformed or specifies an unsupported model alias. Verify that your model parameter matches one of the current public Fikra aliases (e.g., fikra-flash, fikra-pro-20b) and that the request body conforms to the OpenAI-style chat-completions schema.
• 401 Unauthorized: The Authorization header is missing, invalid, or the API key is inactive. Ensure you are using a valid fk_live_... key from your Fikra dashboard and that it is correctly formatted as Bearer <key>.
• 402 Payment Required: Your token-credit wallet balance is insufficient to process the request. Top up your wallet via the Fikra dashboard using Paystack billing (M-Pesa and cards are accepted).
• 429 Too Many Requests: You have exceeded the current rate limit. Unverified accounts are limited to 30 RPM, while trusted accounts are limited to 100 RPM. Implement backoff logic to handle this gracefully.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. This is a transient error; retrying after a delay is recommended.

Handling Timeouts and Retries

The OpenAI SDK does not automatically retry on all errors. For 429 and 503 responses, you should implement exponential backoff to avoid overwhelming the service and to respect rate limits.

Exponential Backoff Example

Below is a compact Python example using the openai library and time module to handle 429 and 503 errors with exponential backoff:

import time
import openai

client = openai.OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key="${FIKRA_API_KEY}"
)

def chat_with_retry(messages, model="fikra-flash", max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages
            )
            return response
        except openai.RateLimitError:
            # 429: Rate limit exceeded
            wait_time = 2 ** attempt
            print(f"Rate limit hit. Retrying in {wait_time}s...")
            time.sleep(wait_time)
        except openai.APIStatusError as e:
            if e.status_code == 503:
                # 503: Service unavailable
                wait_time = 2 ** attempt
                print(f"Service unavailable. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded")

# Example usage
messages = [{"role": "user", "content": "Hello, Fikra!"}]
result = chat_with_retry(messages)
print(result.choices[0].message.content)

Best Practices

1. Check Model Availability: Always verify that the model alias you are using is currently supported. Check the Fikra model registry for the latest list of available models.
2. Monitor Wallet Balance: Ensure your token-credit wallet has sufficient balance to avoid 402 errors.
3. Respect Rate Limits: Adhere to the 30 RPM (unverified) or 100 RPM (trusted) limits to minimize 429 errors.
4. Handle Transient Errors: Use exponential backoff for 429 and 503 errors to improve resilience.
5. Avoid Hardcoded Keys: Store your FIKRA_API_KEY in environment variables or a secure secrets manager.

Note on Failover and SLAs

Fikra API does not currently offer automatic failover, dedicated capacity, or uptime SLAs. For production workloads, consider implementing client-side retry logic and monitoring to handle transient failures gracefully.