Troubleshooting Intermittent 502 Errors and API Status Codes

Understanding HTTP Status Codes in Fikra API

When integrating with the Fikra API, specific HTTP status codes indicate distinct failure states. While a 502 Bad Gateway error typically indicates a temporary network issue between the client and the API gateway, the following codes are explicitly defined in Fikra's error handling:

• 400 Bad Request: The request is malformed or references an unsupported model alias. Verify that your model parameter matches one of the current public aliases (e.g., fikra-flash, fikra-pro-20b) and that the JSON payload is valid.
• 401 Unauthorized: The Authorization header is missing, the Bearer token is invalid, or the API 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 resume service.
• 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 is temporarily unavailable. This is a transient error indicating that the backend model service is not currently responding.

Handling Transient Errors with Exponential Backoff

For transient errors such as 429 (rate limit) and 503 (upstream unavailable), implement exponential backoff to avoid overwhelming the service. Do not assume automatic failover or dedicated capacity; instead, retry with increasing delays.

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
payload = {
    "model": "fikra-flash",
    "messages": [{"role": "user", "content": "Hello"}]
}

result = call_fikra_api(payload)

Important Notes

• No SLA Guarantees: Fikra does not currently publish uptime SLAs or guaranteed response times. Treat 503 errors as transient and handle them gracefully in your application logic.
• Rate Limits: Respect the 30 RPM (unverified) or 100 RPM (trusted) limits to avoid frequent 429 errors.
• Model Availability: Always check the model registry in the Fikra dashboard to confirm which aliases are currently active, as availability may vary.