Errors & Status Codes

AVAILABLE

Naagmani returns clear, structured JSON errors with standard HTTP status codes and machine-readable error codes.


Standard Error Schema #

json
{
  "code": "invalid_request",
  "message": "Detailed human-readable explanation of why the request failed.",
  "request_id": "req_01J8F0A2B3C4D5E6F7G8H9J0K1"
}

HTTP Status Codes & Error Codes #

HTTP StatusError CodeDescription & Mitigation
400invalid_requestMalformed JSON payload, unknown model alias without a routing policy, or budget constraint violation.
401invalid_api_keyProvided API Key or Service Token is invalid, revoked, or expired.
403permission_deniedToken lacks the required capability in its capability matrix, or license is required for feature (e.g., model: "auto").
403PROJECT_ACCESS_DENIEDPortal user is not assigned to this project or lacks the necessary project role (viewer, developer, admin).
403ENTITLEMENT_LIMIT_EXCEEDEDThe project has reached its maximum customer member limit or tier quota under the active subscription plan.
404not_foundThe requested project, member, or resource does not exist.
409IDENTITY_COLLISIONThe provided external_user_id or email already exists within this project boundary.
429quota_exceeded / BUDGET_EXHAUSTEDTenant or member has exceeded their configured monthly/daily spending cap or rate limit.
502upstream_failureAll primary and fallback providers in the routing policy candidate list failed.
504upstream_timeoutUpstream model adapter timed out waiting for provider response.

Model Resolution Errors (400 Bad Request) #

Naagmani enforces strict, deterministic model matching. Unconfigured model names or typos will not silently fall back to random providers.

Example: Unconfigured Model Name #

json
{
  "code": "invalid_request",
  "message": "Model 'smart' is not supported or no matching routing policy found. Please configure a routing policy or enable the provider in your credentials.",
  "request_id": "req_01J8F0A2B3C4D5E6F7G8H9J0K1"
}

How to Resolve: #

  1. Direct Provider Model: Request a valid model configured on your active providers (e.g. deepseek-chat, gpt-4o, claude-3-5-sonnet-20241022).
  2. Routing Policy Alias: Create a Virtual Alias routing policy in the Developer Portal named smart (matching the model parameter) and assign target providers.
  3. Autonomous AI Engine: Use "model": "auto" (requires an active Enterprise license).