Troubleshooting OpenRouter 502 Bad Gateway and Fikra API Errors

Understanding the Error Context

The error OpenRouter 502 Bad Gateway indicates that OpenRouter, an external provider, failed to receive a valid response from an upstream server. Fikra API does not serve OpenRouter models or act as a proxy for OpenRouter. If you are encountering this error, you are likely interacting with OpenRouter directly or through a third-party integration that routes to OpenRouter.

If you are using Fikra API (https://api.fikraapi.co.ke/v1), you will not receive OpenRouter-specific errors. Instead, Fikra returns standard HTTP status codes defined below. This guide explains Fikra’s supported error codes and provides a retry strategy for transient failures.

Fikra API Error Codes

Note: Fikra does not guarantee specific uptime SLAs, dedicated capacity, or automatic failover. Always check the Fikra dashboard for account status and wallet balance.

Handling 429 and 503 with Exponential Backoff

For transient errors (429 and 503), use exponential backoff with jitter to avoid overwhelming the service during recovery. Below is a compact Python example using the requests library.

import time
import random
import requests

FIKRA_API_KEY = "your_fikra_api_key"  # Load from environment variable in production
BASE_URL = "https://api.fikraapi.co.ke/v1"


def call_fikra_with_retry(payload, max_retries=5):
    url = f"{BASE_URL}/chat/completions"
    headers = {
        "Authorization": f"Bearer {FIKRA_API_KEY}",
        "Content-Type": "application/json"
    }

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

            if response.status_code in (429, 503):
                # Exponential backoff with jitter
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"Received {response.status_code}. Retrying in {wait_time:.2f}s...")
                time.sleep(wait_time)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise e
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait_time)

    raise Exception("Max retries exceeded for Fikra API call.")


# Example usage
payload = {
    "model": "fikra-flash",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": False
}

try:
    result = call_fikra_with_retry(payload)
    print(result)
except Exception as e:
    print(f"Error: {e}")

Key Considerations

• Rate Limits: Respect Fikra’s RPM limits (30 RPM unverified, 100 RPM trusted). Exceeding these triggers 429.
• No Automatic Failover: Fikra does not automatically switch to alternative providers or models. If a 503 persists, check the Fikra dashboard for service status.
• Model Availability: Model aliases may change. Always verify current aliases in the Fikra model registry.
• External Providers: If you are using OpenRouter or other external providers, consult their respective documentation for 502 and other error handling. Fikra’s error codes and retry logic do not apply to external services.