API Error Codes & Fallback Protocols
The SUPREME Setu Gateway adheres to standard HTTP status codes with OpenAI-compatible JSON error payloads. This document details each status code, common resolution steps, and our automated cross-tier failover mechanics.
Error Response Format
All 4xx and 5xx responses emit a standardized JSON envelope:
json
{
"error": {
"message": "Detailed description of what caused the error.",
"type": "invalid_request_error",
"param": "model",
"code": "model_tier_gated"
}
}HTTP Status Code Matrix
| Status Code | Error Code (code) | Cause | Client Resolution |
|---|---|---|---|
400 Bad Request | invalid_payload | Malformed JSON, unclosed brackets, or missing required messages array. | Validate JSON syntax and inspect request payload against OpenAPI 3.1 schema. |
401 Unauthorized | invalid_api_key | Missing, expired, or malformed API key in Authorization: Bearer header. | Generate a fresh sup_live_... or sup_test_... key in the Developer Console. |
402 Payment Required | insufficient_credits | Account credit balance reached zero (0 units). | Top up credit packs via eSewa, Khalti, or card in your billing dashboard. Requests resume instantly. |
403 Forbidden | tier_gate_violation | Attempted to invoke a higher-tier model (e.g. quantum-pro) without an Elite/Sovereign subscription. | Upgrade account tier or restrict requests to models permitted by your plan (quantum-lite, quantum-flash). |
403 Forbidden | ip_not_whitelisted | API request originated from an IP outside the key's configured CIDR whitelist. | Update CIDR IP allowlist settings in Developer Console or execute from authorized VPC subnets. |
422 Unprocessable Entity | schema_validation_failed | Parameters outside permissible limits (e.g., temperature > 2.0 or invalid tool JSON-RPC schema). | Check field boundaries (temperature 0.0–2.0, top_p 0.0–1.0, valid tool schema definitions). |
429 Too Many Requests | rate_limit_exceeded | Requests per minute (RPM) or tokens per minute (TPM) quota exhausted for current tier. | Read Retry-After header and implement exponential backoff with jitter. |
500 Internal Error | internal_server_error | Unexpected upstream server exception or transient infrastructure fault. | Retry request using exponential backoff. Persistent errors trigger automatic operations alerts. |
503 Service Unavailable | engine_overloaded | Foundation cluster experiencing severe load spike. SmartRouter failover initiated. | Setu automatically routes to redundant failover nodes. If fallback fails, retry after 3–5 seconds. |
Detailed Error Payload Specifications
401 Unauthorized (invalid_api_key)
Returned when an API key is missing or revoked:
json
{
"error": {
"message": "Incorrect API key provided: sup_live_****. You can find or generate your API keys at https://setu.supremeai.dev.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}402 Payment Required (insufficient_credits)
Returned when your credit balance is depleted:
json
{
"error": {
"message": "Your credit balance is exhausted. Top up your balance in Nepali Rupees (NRs) or USD at https://supremeai.services/pricing to resume requests.",
"type": "billing_error",
"param": null,
"code": "insufficient_credits"
}
}403 Forbidden (tier_gate_violation)
Returned when requesting an elite model without appropriate plan tier permissions:
json
{
"error": {
"message": "The model 'quantum-pro' requires Elite or Sovereign tier subscription. Current tier: 'developer'.",
"type": "permission_error",
"param": "model",
"code": "tier_gate_violation"
}
}429 Too Many Requests (rate_limit_exceeded)
Returned with standard HTTP headers indicating when requests may safely resume:
http
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12
x-ratelimit-limit-requests: 1200
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 12s
{
"error": {
"message": "Rate limit reached for tier 'developer'. Limit: 1,200 RPM. Please retry after 12 seconds.",
"type": "requests",
"param": null,
"code": "rate_limit_exceeded"
}
}SmartRouter Cross-Tier Fallback Protocol (503 Mitigation)
To provide 99.95%+ uptime SLAs, the Setu gateway embeds intelligent, zero-downtime fallback chains:
- Primary Cluster Probe: The gateway dispatches the prompt to the primary foundation cluster.
- Health Check & Latency Bounding: If the primary cluster fails to return headers within 3,500ms or returns an HTTP 500/503 status, SmartRouter intercepts the failure before closing the client socket.
- Automated Redundant Cascade: The request is immediately transparently re-routed to a redundant geo-distributed engine (e.g., secondary Asian cluster or transatlantic replica).
- Transparent Client Completion: The client application receives a seamless completion stream without encountering a disconnect.