Troubleshooting HTTP 500 and Related Errors in Fikra API

Understanding HTTP Error Codes

When integrating with the Fikra API, specific HTTP status codes indicate distinct failure states. Note that a generic 500 Internal Server Error is not a standard documented status for Fikra's public endpoints. If you encounter a 500, it typically indicates an unexpected server-side issue. However, most integration issues are resolved by addressing the following supported status codes:

• 400 Bad Request: The request body is malformed, or the specified model alias is not supported or does not exist in the current registry.
• 401 Unauthorized: The Authorization header is missing, the API key is invalid, or the key has been revoked/inactive.
• 402 Payment Required: Your Fikra wallet balance is insufficient to cover the cost of the request.
• 429 Too Many Requests: You have exceeded the rate limit for your account tier (30 RPM for unverified, 100 RPM for trusted accounts).
• 503 Service Unavailable: The upstream model provider is temporarily unavailable. This is a transient error.

Handling 429 and 503 with Exponential Backoff

For transient errors like 429 and 503, implement exponential backoff to retry requests safely. Do not assume automatic failover or dedicated capacity; these errors require client-side retry logic.

Python Example

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_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 in [429, 503]:
                # Exponential backoff with jitter
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                print(f"Received {response.status_code}. Retrying in {delay:.2f}s...")
                time.sleep(delay)
                continue

            response.raise_for_status()
            return response.json()

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

    return None

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

Debugging Checklist

1. Verify Model Alias: Ensure the model field uses a valid public alias (e.g., fikra-flash, fikra-pro-20b). Check the Fikra dashboard for the current model registry.
2. Check API Key: Confirm the key is active in the Fikra dashboard and correctly formatted as fk_live_....
3. Inspect Wallet Balance: If you receive a 402, top up your wallet via the Fikra dashboard. M-Pesa and cards are accepted for billing.
4. Monitor Rate Limits: If you receive a 429, ensure your request frequency stays within your account's RPM limit. Trusted accounts have higher limits than unverified ones.
5. Handle 503s: Treat 503 as a temporary upstream issue. Use the backoff strategy above. Do not assume the service is permanently down.

For persistent issues, contact Fikra support through the dashboard.