What do Fikra API error codes mean?
When a request fails, the Fikra API returns a standard HTTP status code indicating the nature of the failure, accompanied by a unified JSON error object. Understanding these codes ensures your application can gracefully handle authentication failures, depleted token wallets, and hardware limits.
The Standardized JSON Error Object
Regardless of whether an error originates from our billing proxy, the Redis security shield, or the inference hardware itself, it is normalized into the following predictable format.
| Object Key | Description |
|---|---|
| message | A human-readable string explaining why the request failed. |
| type | The classification of the error (e.g., invalid_request_error, api_error, billing_error). |
| param | If the error is tied to a specific JSON key in your payload (like passing a bad model string), it will be listed here. |
| code | A machine-readable programmatic code (e.g., insufficient_quota) designed to trigger logical fallbacks in your code. |
4xx Client Errors (Action Required)
Errors in the 4xx range indicate that the request provided by your application is malformed, unauthorized, or violating limits. These errors must be fixed in your codebase or dashboard account.
| Status Code | Resolution Strategy |
|---|---|
| 400 Bad Request | Your JSON payload is invalid or you provided parameters that the selected model does not support. Double-check your array syntax and ensure the model string matches the registry exactly. |
| 401 Unauthorized | Your API key is missing, malformed, or revoked. Check your Authorization: Bearer header. Ensure you are not accidentally passing environment variables with trailing spaces. |
| 402 Payment Required | Your global token wallet has reached zero. Fikra API prevents negative balances. Navigate to the dashboard and initiate an M-Pesa or card top-up to resume service instantly. |
| 404 Not Found | The endpoint you are trying to reach does not exist. Ensure your base URL is explicitly set to https://api.fikraapi.co.ke/v1 and not appended with duplicate paths. |
| 429 Too Many Requests | You have hit the Redis rate limits for your specific account tier. Throttle your request loop or complete your first transaction to unlock the Trusted Tier (100 RPM). |
5xx Server Errors (Temporary)
Errors in the 5xx range indicate an issue on our end. These are generally related to temporary proxy congestion or brief NPU hardware resets.
| Status Code | System Status |
|---|---|
| 500 Internal Error | An unexpected failure occurred within the monolithic proxy engine. Retrying the request after a brief delay usually resolves this. |
| 502 Bad Gateway | The Fikra proxy was unable to establish a secure connection to the underlying Groq inference cluster. |
| 503 Service Unavailable | Our inference nodes are undergoing scheduled maintenance or experiencing extreme, temporary load saturation. |
How should I programmatically handle exceptions?
Since Fikra API aligns with the OpenAI specification, you can utilize native SDK exception classes to handle 401s, 402s, and 429s without writing custom network interceptors.