Troubleshooting APIConnectionError and HTTP Status Codes

When integrating with the Fikra API, you may encounter connection errors or specific HTTP status codes. This guide explains the supported meanings of these responses and provides a retry strategy for transient failures.

Common HTTP Status Codes

• 400 Bad Request: The request is malformed or references an unsupported model alias. Verify that your model field matches one of the current public aliases (e.g., fikra-flash, fikra-pro-20b) and that the JSON payload is valid.
• 401 Unauthorized: The API key is missing, invalid, or inactive. Ensure the Authorization: Bearer fk_live_... header is present and that the key is active in your Fikra dashboard.
• 402 Payment Required: Your token-credit wallet balance is insufficient. Top up your wallet via the Fikra dashboard to continue making requests.
• 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 logic to handle this status.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. This is a transient error; retrying after a delay is recommended.

Handling 429 and 503 with Exponential Backoff

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

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):
    url = f"{BASE_URL}/chat/completions"
    headers = {
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    }

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

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

        return response

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

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

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

Notes

• Do not assume automatic failover or dedicated capacity; Fikra does not currently advertise SLAs or reserved throughput.
• Always check the Fikra dashboard for your account's verification status to understand your applicable rate limits.
• If you consistently receive 503 errors, verify the status of the upstream provider through official channels, as Fikra does not guarantee specific provider behavior.