Reference
Response codes
HTTP status codes Zelyx returns and what each means for your application.
Zelyx-generated codes
These codes are returned by Zelyx before the provider is contacted. No tokens are consumed and no cost is incurred.
| Code | Reason | What to do |
|---|---|---|
| 401 | Missing or malformed Authorization header. The Zelyx key was not provided or does not match the expected format. | Check that your api_key starts with nk_ and is being sent in the Authorization: Bearer header or x-api-key header. |
| 403 | Key not found, revoked, or policy violation (model block list, allow list, max tokens exceeded). | Verify the key exists and is active on the API Keys page. If the model is blocked, check the key's allowed/blocked model settings. |
| 402 | Budget exhausted. The company, team, project, per-key, per-model, or run budget is depleted. | Check the Budgets page to see which layer is exhausted. Either increase the cap or wait for the daily reset at midnight UTC. |
| 429 | Loop detected. The gate identified a repeating call pattern within the configured window and the action is set to block. | Back off and re-evaluate your agent logic. Check loop detection config in Settings. |
| 503 | Provider key could not be decrypted or the vault is unreachable. | Contact your workspace admin to verify the provider key is still valid. If this persists, check the status page. |
Provider-forwarded codes
These codes are returned by the AI provider and passed through by Zelyx unchanged. They indicate provider-level issues, not Zelyx enforcement.
| Code | Typical cause |
|---|---|
| 200 | Success. Normal response. |
| 400 | Bad request — malformed JSON, unsupported parameter, or invalid model name for the provider. |
| 429 | Provider rate limit exceeded. This is distinct from Zelyx's loop-detection 429. The response body will identify the source. |
| 500/502/503 | Provider outage or transient error. Retry with exponential backoff. |
TipYou can distinguish a Zelyx-generated 402 from a provider 402 by checking the response body. Zelyx returns a JSON body with a
detail field: { "detail": "daily_budget_exceeded" }. Provider errors have provider-specific formats.Response body for blocked calls
// HTTP 402 — budget exceeded
{
"detail": "daily_budget_exceeded"
}
// HTTP 403 — gate policy (model block)
{
"detail": "model_not_allowed",
"decision": "block",
"reason": "model_not_allowed",
"explanation": "Model gpt-4o is not in the allowed models list for this key."
}
// HTTP 429 — loop detected
{
"detail": "loop_detected",
"call_count": 12,
"window_seconds": 60
}