Troubleshooting: Maximum Context Length Exceeded

Understanding the Error

The error OpenAI error Maximum context length exceeded indicates that the total number of tokens in your request (system prompt + user messages + assistant history) exceeds the maximum context window supported by the selected Fikra model.

Fikra API is compatible with OpenAI-style chat-completions requests. While the error message may reference OpenAI conventions, the limit is enforced by the specific Fikra model alias you are using (e.g., fikra-flash, fikra-pro-20b).

Resolution Steps

1. Check Model Limits: Different Fikra models have different context windows. Check the model registry in the Fikra dashboard for the specific token limit of your selected alias.
2. Reduce Input Size:
3. Trim the system prompt.
4. Remove older conversation turns from the messages array.
5. Summarize previous context if necessary.
6. Verify Model Alias: Ensure you are using a valid, currently available Fikra alias. An unsupported model may return a 400 error, which can sometimes be misinterpreted if the model does not exist or has different constraints.

HTTP Status Codes Reference

If you encounter other errors, refer to these standard Fikra API responses:

• 400 Bad Request: Malformed request structure or unsupported model alias.
• 401 Unauthorized: Missing, invalid, or inactive API key. Ensure your Authorization: Bearer fk_live_... header is correct.
• 402 Payment Required: Insufficient wallet balance. Top up via the Fikra dashboard using Paystack (M-Pesa or cards).
• 429 Too Many Requests: Rate limit exceeded. Unverified accounts are limited to 30 RPM; trusted accounts to 100 RPM.
• 503 Service Unavailable: Upstream provider temporarily unavailable. Retry with backoff.

Handling 429 and 503 Errors

For rate limits (429) or temporary unavailability (503), implement exponential backoff. Do not assume automatic failover or dedicated capacity.

Python Example: Exponential Backoff

import time
import random
import openai

client = openai.OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key="${FIKRA_API_KEY}"
)

def call_fikra_with_backoff(messages, model="fikra-flash", max_retries=5):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages
            )
            return response
        except openai.RateLimitError:
            # 429: Rate limit exceeded
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limit hit. Retrying in {wait_time:.2f}s...")
            time.sleep(wait_time)
        except openai.APIStatusError as e:
            if e.status_code == 503:
                # 503: Service unavailable
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"Service unavailable. Retrying in {wait_time:.2f}s...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded for 429/503 errors.")

# Usage
# result = call_fikra_with_backoff([{"role": "user", "content": "Hello"}])

Notes

• Fikra does not currently offer automatic failover to other models.
• No uptime SLAs or dedicated capacity guarantees are provided.
• Always validate your API key and wallet balance before debugging context issues.