Handling AI API Rate Limits and Errors in Fikra

Understanding Fikra API Error Codes

When integrating with the Fikra API, specific HTTP status codes indicate distinct failure states. Properly handling these codes ensures robust application behavior.

• 400 Bad Request: The request body is malformed, or the specified model alias is not supported. Verify your JSON structure and ensure the model field matches 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 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 requests per minute (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.

Implementing Exponential Backoff

For 429 and 503 errors, use exponential backoff to avoid overwhelming the API. The following Python example demonstrates a compact retry strategy.

import time
import requests

FIKRA_API_KEY = "your_api_key_here"
BASE_URL = "https://api.fikraapi.co.ke/v1"

def call_fikra_api(payload, max_retries=5):
    headers = {
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    }

    for attempt in range(max_retries):
        response = requests.post(f"{BASE_URL}/chat/completions", headers=headers, json=payload)

        if response.status_code in [429, 503]:
            # Exponential backoff: 1s, 2s, 4s, 8s, 16s
            wait_time = 2 ** attempt
            print(f"Received {response.status_code}. Retrying in {wait_time}s...")
            time.sleep(wait_time)
            continue

        if response.status_code == 402:
            print("Insufficient wallet balance. Please top up.")
            return None

        if response.status_code == 401:
            print("Invalid or inactive API key.")
            return None

        if response.status_code == 400:
            print("Malformed request or unsupported model.")
            return None

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

        # For other unexpected errors
        print(f"Unexpected error: {response.status_code}")
        return None

    print("Max retries exceeded.")
    return None

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

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

Best Practices

1. Monitor Wallet Balance: Regularly check your token-credit wallet to avoid 402 errors during peak usage.
2. Respect Rate Limits: Design your application to queue requests if you anticipate exceeding 30 RPM (unverified) or 100 RPM (trusted).
3. Handle Transient Errors: Treat 503 errors as temporary and use backoff to retry. Do not assume permanent failure.
4. Validate Requests: Ensure your request payload is valid and uses supported model aliases to prevent 400 errors.

For the most up-to-date model availability and rate limit details, check the Fikra model registry in your dashboard.