Troubleshooting 503 Service Unavailable and Rate Limits

Understanding HTTP Status Codes

When integrating with the Fikra API, specific HTTP status codes indicate distinct failure states. Understanding these codes helps you implement robust error handling.

• 400 Bad Request: The request is malformed or references an unsupported model alias. Verify your JSON structure and ensure the model field matches a current public 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. Ensure 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.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. This is a transient error indicating that the backend service is currently unable to handle the request due to overload or maintenance.

Handling 429 and 503 Errors

Both 429 (rate limit) and 503 (service unavailable) errors are transient. The recommended approach is to implement exponential backoff with jitter to avoid hammering the API during outages or rate-limit windows.

Exponential Backoff Example

The following Python example demonstrates how to handle 429 and 503 errors using exponential backoff. It retries the request up to 5 times, increasing the wait time between attempts.

import time
import random
import requests

FIKRA_API_KEY = "your_api_key_here"  # Replace with your actual key
BASE_URL = "https://api.fikraapi.co.ke/v1"


def call_fikra_api(payload):
    url = f"{BASE_URL}/chat/completions"
    headers = {
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    }

    max_retries = 5
    base_delay = 1.0  # Start with 1 second

    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=payload)

            # Success
            if response.status_code == 200:
                return response.json()

            # Transient errors: 429 (Rate Limit) and 503 (Service Unavailable)
            if response.status_code in [429, 503]:
                # Calculate delay with exponential backoff and jitter
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                print(f"Received {response.status_code}. Retrying in {delay:.2f} seconds...")
                time.sleep(delay)
                continue

            # Non-retryable errors
            else:
                print(f"Error {response.status_code}: {response.text}")
                break

        except requests.exceptions.RequestException as e:
            print(f"Request exception: {e}")
            if attempt < max_retries - 1:
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise

    return None

# Example usage
payload = {
    "model": "fikra-flash",
    "messages": [
        {"role": "user", "content": "Hello, Fikra!"}
    ]
}

result = call_fikra_api(payload)
if result:
    print(result)

Important Notes

• No Automatic Failover: Fikra does not promise automatic failover to other providers or models. If a 503 error persists, the upstream service may be down.
• Rate Limits: Ensure your application respects the 30 RPM (unverified) or 100 RPM (trusted) limits to avoid frequent 429 errors.
• Wallet Balance: A 402 error indicates a billing issue, not a service outage. Check your wallet balance in the Fikra dashboard.
• Model Availability: Always verify that the model alias you are using is currently available in the Fikra model registry.