Troubleshooting 503 and 429 Errors in Fikra API

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 or engine is temporarily unavailable. This is a transient error indicating that the backend service is currently overloaded or undergoing maintenance.

Handling 429 and 503 Errors

Both 429 and 503 errors are transient. Implementing an exponential backoff strategy is recommended to handle these scenarios gracefully without overwhelming the service.

Exponential Backoff Example

The following Python example demonstrates how to handle 429 and 503 errors using exponential backoff. It retries the request with increasing delays.

import time
import requests
import os

FIKRA_API_KEY = os.getenv("FIKRA_API_KEY")
BASE_URL = "https://api.fikraapi.co.ke/v1"

def call_fikra_api(model="fikra-flash", max_retries=5):
    url = f"{BASE_URL}/chat/completions"
    headers = {
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    }
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": "Hello"}]
    }

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

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

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

            # Handle other errors immediately
            raise Exception(f"API Error {response.status_code}: {response.text}")

        except requests.exceptions.RequestException as e:
            print(f"Request failed: {e}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

    raise Exception("Max retries exceeded for transient errors.")

# Example usage
# result = call_fikra_api()

Important Notes

• No Automatic Failover: Fikra does not promise automatic failover to other providers or dedicated capacity.
• No Uptime SLA: There are no guaranteed uptime SLAs or specific provider-behavior guarantees.
• Rate Limits: Always check your account status in the Fikra dashboard to confirm whether you are on the 30 RPM (unverified) or 100 RPM (trusted) tier.
• Model Availability: Model aliases may change. Always check the model registry in the Fikra dashboard for the latest available models.