Handling HTTP 429 in LangChain with Fikra API

Understanding HTTP 429 in Fikra API

When integrating Fikra API with LangChain, an HTTP 429 status code indicates that the request rate limit has been exceeded. Fikra enforces rate limits based on account verification status:

• Unverified accounts: 30 requests per minute (RPM).
• Trusted accounts: 100 requests per minute (RPM).

Common Fikra API Error Codes

Handling 429 and 503 with Exponential Backoff

LangChain does not automatically retry failed requests by default. You should implement retry logic with exponential backoff to handle transient errors (429 and 503) gracefully.

Example: Exponential Backoff in Python

import time
import random
from langchain_openai import ChatOpenAI

FIKRA_API_KEY = "your_fikra_api_key"  # Load from environment variable in production

client = ChatOpenAI(
    model="fikra-flash",
    api_key=FIKRA_API_KEY,
    base_url="https://api.fikraapi.co.ke/v1",
)

def call_with_backoff(prompt, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.invoke(prompt)
            return response.content
        except Exception as e:
            # Check if the error is a 429 or 503
            status_code = getattr(e, "status_code", None)
            if status_code in (429, 503):
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"Attempt {attempt + 1} failed with {status_code}. Retrying in {wait_time:.2f}s...")
                time.sleep(wait_time)
            else:
                raise e
    raise Exception("Max retries exceeded for 429/503 errors.")

# Usage
result = call_with_backoff("Hello, Fikra!")
print(result)

Best Practices

1. Monitor Rate Limits: Track your request frequency to stay within your account's RPM limit.
2. Use Trusted Accounts: Verify your account to increase your rate limit from 30 RPM to 100 RPM.
3. Handle 402 Errors: If you receive a 402 error, top up your token-credit wallet via the Fikra dashboard.
4. Avoid Hardcoded Keys: Always load FIKRA_API_KEY from environment variables or a secure secrets manager.
5. Check Model Availability: Ensure the model alias (e.g., fikra-flash, fikra-pro-20b) is currently available in the Fikra model registry.

Notes

• Fikra API is OpenAI-compatible, so LangChain's ChatOpenAI client works with minor configuration changes.
• Streaming is supported via stream: true and Server-Sent Events (SSE).
• No automatic failover, dedicated capacity, or uptime SLAs are guaranteed. Always implement client-side retry logic for resilience.