Handling Rate Limits in Vercel AI SDK with Fikra API

When integrating Fikra API with the Vercel AI SDK, you may encounter specific HTTP status codes indicating request constraints or system states. This guide explains the supported meanings and provides a strategy for handling transient errors.

Status Code Meanings

• 400 Bad Request: The request is malformed or references an unsupported model alias. Verify that your model parameter matches one of the current public Fikra aliases (e.g., fikra-flash, fikra-pro-20b) and that the request body conforms to the OpenAI-style chat-completions schema.
• 401 Unauthorized: The Authorization header is missing, the API key is invalid, or the key is inactive. Ensure you are using a valid fk_live_... key from your Fikra dashboard and that it is correctly passed via the Authorization: Bearer <key> header.
• 402 Payment Required: Your Fikra token-credit wallet balance is insufficient to cover the cost of the request. Top up your wallet via the Fikra dashboard to resume service.
• 429 Too Many Requests: You have exceeded the current rate limit. Fikra enforces 30 requests per minute (RPM) for unverified accounts and 100 RPM for trusted accounts. This limit is applied per API key.
• 503 Service Unavailable: The upstream provider is temporarily unavailable. This is a transient error indicating that the backend infrastructure is not currently able to process the request.

Handling 429 and 503 Errors

For 429 and 503 responses, implement an exponential backoff strategy to avoid overwhelming the service during recovery. The Vercel AI SDK allows you to handle errors via the onError callback or by wrapping the generateText/streamText calls in a retry loop.

Below is a compact example of an exponential backoff implementation in JavaScript/TypeScript:

import { generateText } from 'ai';
import { createOpenAI } from '@ai-sdk/openai';

const fikra = createOpenAI({
  baseURL: 'https://api.fikraapi.co.ke/v1',
  apiKey: process.env.FIKRA_API_KEY,
});

async function callFikraWithRetry(prompt: string, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const result = await generateText({
        model: fikra('fikra-flash'),
        prompt: prompt,
      });
      return result.text;
    } catch (error: any) {
      const status = error.status || error.response?.status;

      // Only retry on 429 (Rate Limit) and 503 (Service Unavailable)
      if ((status === 429 || status === 503) && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s...
        console.warn(`Attempt ${attempt + 1} failed with status ${status}. Retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        // Re-throw non-retryable errors or if max retries exceeded
        throw error;
      }
    }
  }
}

// Usage
// const response = await callFikraWithRetry("Hello Fikra");

Important Notes

• No Automatic Failover: Fikra does not currently offer automatic failover to alternative providers. If a 503 persists, the upstream service is unavailable.
• Rate Limits: The 30/100 RPM limits are hard caps. Exceeding them will result in 429 errors. Monitor your usage in the Fikra dashboard to ensure you stay within your tier.
• Model Availability: Always check the Fikra model registry for the latest available aliases, as availability may vary.