What do Fikra API error codes mean?
When a request fails, 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 blocks, empty cash wallets, and payload violations.
The Standardized JSON Error Object
Regardless of whether an error originates from our billing proxy or payload validation, it is normalized into the following predictable schema.
| 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). |
| 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.
| Status Code | Resolution Strategy |
|---|---|
| 400 Bad Request | Your JSON payload is invalid or contains prohibited parameters (e.g., trying to force reasoning_effort). Verify the model string against the registry. |
| 401 Unauthorized | API key is missing, malformed, or revoked. Check your Authorization: Bearer header. |
| 402 Payment Required | Your global cash wallet balance is depleted. Fikra API terminates sessions immediately to prevent negative balances. Top up via the dashboard. |
| 404 Not Found | Invalid URL path. Ensure base URL is exactly https://api.fikraapi.co.ke/v1. |
| 413 Payload Too Large | The prompt exceeds the context window of the selected model (e.g., passing 100k tokens to fikra-fast-8b). |
| 422 Unprocessable | Semantic schema failure. You may be passing a string instead of an integer for max_tokens. |
| 429 Too Many Requests | You have breached your Fikra Account Tier RPM threshold. Apply exponential backoff and retry. |
5xx Server Errors & Internal Retries
Under the hood, the Fikra API proxy actively catches transient upstream errors (408 Request Timeout, 429 Upstream Rate Limit, 500, 502, 503, and 504 Gateway Timeout) and seamlessly retries your payload across backup API keys and fallback routing engines. You will only receive the following errors if all fallback routes and secondary keys are entirely exhausted.
| Status Code | System Status |
|---|---|
| 500 Internal Error | An unexpected failure occurred within the monolithic proxy engine before the request could be routed. |
| 502 Bad Gateway | The Fikra proxy was unable to establish a secure connection to the underlying inference cluster, and all fallbacks have failed. |
| 503 Service Unavailable | Inference nodes are undergoing scheduled maintenance. |