Troubleshooting Rate Limits and API Errors in Fikra API

This guide addresses common HTTP status codes returned by the Fikra API, specifically focusing on rate limiting (429) and service availability (503). It also covers authentication and request validation errors.

Understanding HTTP Status Codes

• 400 Bad Request: The request is malformed or references an unsupported model alias. Verify that your model parameter matches one of the current public Fikra aliases (e.g., fikra-flash, fikra-pro-20b) and that the JSON payload is valid.
• 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. Fikra enforces 30 RPM for unverified accounts and 100 RPM for trusted accounts. This limit is applied per API key.
• 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.

Handling 429 and 503 Errors

When encountering a 429 or 503 response, implement an exponential backoff strategy to retry the request. This approach reduces load on the API and increases the likelihood of a successful retry.

Exponential Backoff Example (Python)

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

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

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

            # Handle rate limits and service unavailability
            if response.status_code in [429, 503]:
                # Calculate exponential backoff with 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

            # Other errors (400, 401, 402) should not be retried automatically
            raise Exception(f"API Error {response.status_code}: {response.text}")

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(base_delay * (2 ** attempt))

    raise Exception("Max retries exceeded")

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

try:
    result = call_fikra_api(payload)
    print(result)
except Exception as e:
    print(f"Error: {e}")

Best Practices

1. Monitor Rate Limits: Keep track of your request frequency to stay within the 30 RPM (unverified) or 100 RPM (trusted) limits.
2. Validate Requests: Ensure your API key is active and your wallet has sufficient balance before making requests to avoid 401 and 402 errors.
3. Use Exponential Backoff: Always implement backoff for 429 and 503 errors to handle transient issues gracefully.
4. Check Model Availability: Verify that the model alias you are using is currently supported by checking the Fikra model registry.

For further assistance, refer to the Fikra API documentation or contact support through the Fikra dashboard.