Troubleshooting LLM API Retries and Backoff Strategies

Handling Errors and Retries

When integrating with the Fikra API, implement robust error handling to manage transient failures and rate limits. The following HTTP status codes indicate specific conditions that may require retry logic.

Status Code Meanings

• 400 Bad Request: The request is malformed or references an unsupported model alias. Do not retry; fix the request payload or model name.
• 401 Unauthorized: The API key is missing, invalid, or inactive. Do not retry; verify your FIKRA_API_KEY environment variable and dashboard status.
• 402 Payment Required: Your token-credit wallet balance is insufficient. Do not retry; top up your wallet via the Fikra dashboard.
• 429 Too Many Requests: You have exceeded the current rate limit (30 RPM for unverified accounts, 100 RPM for trusted accounts). Retry with exponential backoff.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. Retry with exponential backoff.

Exponential Backoff Strategy

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

import os
import time
import requests

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

def call_fikra_api(model="fikra-flash", max_retries=3):
    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):
        response = requests.post(url, headers=headers, json=payload)

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

        if response.status_code == 200:
            return response.json()
        else:
            # Non-retryable errors (400, 401, 402)
            raise Exception(f"API Error {response.status_code}: {response.text}")

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

# Example usage
# result = call_fikra_api()

Notes

• No Automatic Failover: Fikra does not promise automatic failover to other providers or dedicated capacity.
• Rate Limits: Current limits are 30 RPM for unverified accounts and 100 RPM for trusted accounts. Check the Fikra dashboard for your account status.
• Model Availability: Always verify model aliases (e.g., fikra-flash, fikra-pro-20b) against the current model registry, as availability may vary.
• No SLA Guarantees: Fikra does not currently publish uptime SLAs or support-response guarantees. Monitor your application's error rates and adjust retry logic accordingly.