Troubleshooting 429 Rate Limit Errors in Fikra API

Understanding HTTP 429: Rate Limit Exceeded

A 429 status code indicates that your request exceeded the current rate limit for your account. Fikra enforces the following limits: - Unverified accounts: 30 requests per minute (RPM) - Trusted accounts: 100 requests per minute (RPM)

Common Causes

1. Burst traffic: Sending more than 30 or 100 requests within a 60-second window.
2. Retry storms: Aggressive immediate retries after a failure.
3. Shared keys: Multiple services or users sharing the same API key.

Resolution Steps

1. Verify your account status: Check the Fikra dashboard to confirm whether your account is verified or trusted.
2. Implement backoff: Use exponential backoff with jitter to space out retries.
3. Queue requests: Buffer high-volume requests client-side to stay within RPM limits.
4. Rotate keys: If multiple services share a key, consider using separate keys per service if your plan supports it.

Exponential Backoff Example (Python)

import time
import random
import requests

FIKRA_API_KEY = "your_api_key_here"  # Load from environment variable in production
BASE_URL = "https://api.fikraapi.co.ke/v1"


def call_fikra_with_backoff(payload, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(
            f"{BASE_URL}/chat/completions",
            headers={
                "Authorization": f"Bearer {FIKRA_API_KEY}",
                "Content-Type": "application/json"
            },
            json=payload
        )

        if response.status_code in (429, 503):
            # Exponential backoff with jitter
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Received {response.status_code}. Retrying in {wait_time:.2f}s...")
            time.sleep(wait_time)
            continue

        if response.status_code == 200:
            return response.json()
        else:
            # Handle other errors (400, 401, 402, etc.)
            raise Exception(f"API Error {response.status_code}: {response.text}")

    raise Exception("Max retries exceeded for 429/503 errors.")


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

try:
    result = call_fikra_with_backoff(payload)
    print(result)
except Exception as e:
    print(e)

Other Relevant Status Codes

• 400: Malformed request or unsupported model alias. Check the model registry for valid aliases.
• 401: Missing, invalid, or inactive API key. Verify your key in the Fikra dashboard.
• 402: Insufficient wallet balance. Top up via Paystack (M-Pesa or card) in the dashboard.
• 503: Upstream provider temporarily unavailable. Retry with backoff as shown above.

Notes

• Fikra does not guarantee automatic failover, dedicated capacity, or uptime SLAs.
• Always check the Fikra dashboard for real-time account status and wallet balance.
• For production use, load FIKRA_API_KEY from an environment variable, not hardcoded strings.