Troubleshooting OpenAI-Style Timeout and Connection Errors

When integrating with Fikra API using OpenAI-style clients, timeout errors or connection resets can occur due to network latency, rate limiting, or temporary upstream unavailability. This guide explains how to interpret common HTTP status codes and implement robust retry logic.

Understanding HTTP Status Codes

Fikra API returns standard HTTP status codes to indicate the state of your request:

• 400 Bad Request: The request body is malformed, or the specified model alias is not supported. Verify that your JSON payload is valid and that you are using a current Fikra alias (e.g., fikra-flash, fikra-pro-20b).
• 401 Unauthorized: The Authorization header is missing, the API key is invalid, or the key has been deactivated. Ensure your FIKRA_API_KEY environment variable is set correctly and that the key is active in the Fikra dashboard.
• 402 Payment Required: Your account has an insufficient token-credit balance. Top up your wallet via the Fikra dashboard to resume service.
• 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 Transient Errors

Timeouts often correlate with 429 or 503 responses. To ensure reliability, implement exponential backoff with jitter. This approach prevents overwhelming the API during transient failures.

Exponential Backoff Example (Python)

The following example demonstrates how to handle 429 and 503 errors using exponential backoff. It uses the openai Python client configured for Fikra API.

import os
import time
import random
from openai import OpenAI

client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.getenv("FIKRA_API_KEY")
)

def chat_with_backoff(messages, model="fikra-flash", max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages
            )
            return response
        except Exception as e:
            # Check for rate limit (429) or service unavailable (503)
            if hasattr(e, 'status_code') and e.status_code in (429, 503):
                # Calculate backoff delay: base * 2^attempt + jitter
                base_delay = 1.0
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                print(f"Attempt {attempt + 1} failed with status {e.status_code}. Retrying in {delay:.2f}s...")
                time.sleep(delay)
            else:
                # Non-retryable error (e.g., 400, 401, 402)
                raise e
    raise Exception("Max retries exceeded")

# Example usage
try:
    result = chat_with_backoff(
        messages=[{"role": "user", "content": "Hello Fikra"}],
        model="fikra-flash"
    )
    print(result.choices[0].message.content)
except Exception as e:
    print(f"Error: {e}")

Best Practices

1. Verify Model Aliases: Always check the Fikra model registry to ensure the alias you are using is currently available.
2. Monitor Wallet Balance: A 402 error indicates insufficient credits. Regularly monitor your token-credit wallet to avoid service interruptions.
3. Respect Rate Limits: Adhere to the 30 RPM (unverified) or 100 RPM (trusted) limits to minimize 429 errors.
4. Implement Jitter: Adding random jitter to your backoff delays helps prevent thundering herd problems when multiple clients retry simultaneously.

For further assistance, consult the Fikra API documentation or contact support via the Fikra dashboard.