Troubleshooting Slow Responses and API Errors

If you are experiencing slow responses or errors when using Fikra API, this guide explains the standard HTTP status codes and how to handle them. Note that Fikra API is an independent service; performance may vary based on current load and model availability.

Understanding 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 your JSON payload is valid.
• 401 Unauthorized: Your API key is missing, invalid, or inactive. Ensure you are sending the Authorization: Bearer fk_live_... header with a valid key from 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 gracefully.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. This is a transient error; retrying after a delay is recommended.

Handling 429 and 503 Errors with Exponential Backoff

When encountering 429 or 503 errors, use exponential backoff to avoid overwhelming the service. Below is a compact Python example using the requests library.

import time
import requests

base_url = "https://api.fikraapi.co.ke/v1"
api_key = "YOUR_FIKRA_API_KEY"  # Replace with your actual key

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

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

def make_request_with_backoff(max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(f"{base_url}/chat/completions", headers=headers, json=payload)

        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

        if response.status_code == 200:
            return response.json()
        else:
            print(f"Unexpected error: {response.status_code} - {response.text}")
            break

    return None

result = make_request_with_backoff()
if result:
    print(result)

Best Practices

1. Monitor Rate Limits: Keep track of your RPM usage to avoid hitting 429 errors.
2. Check Wallet Balance: Ensure your token-credit wallet has sufficient balance to prevent 402 errors.
3. Validate Model Aliases: Use only currently supported model aliases to avoid 400 errors.
4. Implement Retries: Always include retry logic with exponential backoff for transient errors (429, 503).

For the most up-to-date model availability and rate limits, check the Fikra dashboard or model registry.