Troubleshooting Exponential Backoff with Fikra API

When integrating with the Fikra API, you may encounter transient errors that require retry logic. This guide explains the specific HTTP status codes returned by Fikra and provides a compact example of implementing exponential backoff for rate limiting and service unavailability.

Understanding Fikra API Status Codes

• 400 Bad Request: The request is malformed or references an unsupported model alias. Check your payload structure and ensure the model field matches a valid Fikra alias (e.g., fikra-flash, fikra-pro-20b).
• 401 Unauthorized: The Authorization header is missing, the API key is invalid, or the key is inactive. Verify that you are using a valid fk_live_... key from your Fikra dashboard.
• 402 Payment Required: Your token-credit wallet balance is insufficient to process the request. Top up your wallet via the Fikra dashboard to continue.
• 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 to handle this gracefully.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. This is a transient error; retrying after a delay is recommended.

Exponential Backoff Implementation

For 429 and 503 errors, use exponential backoff to avoid overwhelming the service. The example below uses the openai Python library configured for Fikra's OpenAI-compatible endpoint.

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 retryable status codes: 429 (Rate Limit) and 503 (Service Unavailable)
            status_code = getattr(e, 'status_code', None)
            if status_code in [429, 503] and attempt < max_retries - 1:
                # Calculate backoff delay: base_delay * (2 ** attempt) + jitter
                base_delay = 1.0
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise

# Example usage
messages = [{"role": "user", "content": "Hello Fikra"}]
try:
    result = chat_with_backoff(messages)
    print(result.choices[0].message.content)
except Exception as e:
    print(f"Request failed after retries: {e}")

Key Considerations

• Rate Limits: Respect the 30 RPM (unverified) or 100 RPM (trusted) limits. If you consistently hit 429, consider upgrading your account status or optimizing request frequency.
• No Automatic Failover: Fikra does not promise automatic failover to other providers. If you receive 503, the service is temporarily down; retrying with backoff is the standard recovery mechanism.
• Wallet Balance: A 402 error is not transient. Do not retry; instead, prompt the user to top up their wallet.
• Model Availability: Always verify that the model alias you are using is currently available in the Fikra model registry. Unsupported models will return 400.