Error Codes

The Fikra API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with our servers.

Standard HTTP Status Codes

• 200 - OK: Everything worked as expected.
• 400 - Bad Request: The request was unacceptable, often due to missing a required parameter or invalid JSON.
• 401 - Unauthorized: No valid API key provided.
• 402 - Payment Required: Your Fikra account balance is depleted. You must top up via the dashboard to resume inference.
• 403 - Forbidden: Your API key has been disabled or revoked.
• 429 - Too Many Requests: You have hit your rate limit. Wait a minute before sending more requests.
• 500, 502, 503, 504 - Server Errors: Something went wrong on our end or with the upstream AI provider.

Error Payload Structure

When an error occurs, the Fikra API returns a standard OpenAI-compatible JSON payload so your existing parsers won't break:

{
  "error": {
    "message": "Insufficient balance. Please top up your Fikra account.",
    "type": "insufficient_quota",
    "param": null,
    "code": 402
  }
}

Handling Errors in Code

If you are using the official OpenAI SDK, these HTTP codes are automatically wrapped into exceptions that you can catch and handle gracefully. Pay special attention to catching the 402 status code for billing events.

import openai

try:
    response = client.chat.completions.create(
        model="llama3-70b-8192",
        messages=[{"role": "user", "content": "Hello"}]
    )
except openai.AuthenticationError:
    print("Your Fikra API key is invalid.")
except openai.RateLimitError:
    print("You are sending requests too quickly. Please slow down.")
except openai.APIStatusError as e:
    if e.status_code == 402:
        print("Out of credits! Time to top up your Fikra wallet.")
    else:
        print(f"Fikra API returned a status error: {e.status_code} - {e.message}")
except openai.APIError as e:
    print(f"Fikra API returned a general API Error: {e}")