Error Codes

Complete reference of 33 error codes across 10 categories returned by the AIBrain Service.

Error response formatjson

{
  "error": {
    "code": "AIBRAIN_1000",
    "message": "Prompt is empty, exceeds token limit, or contains forbidden content",
    "http": 400
  }
}

OrchestrationAIBRAIN_1000-1099

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1000`	400	`INVALID_PROMPT`	Prompt is empty, exceeds token limit, or contains forbidden content	Check prompt length and content against model limits
`AIBRAIN_1001`	400	`INVALID_MODE`	Orchestration mode not recognized (must be single or zar)	Use mode: "single" or mode: "zar"
`AIBRAIN_1002`	502	`PROVIDER_ERROR`	Upstream LLM provider returned an error during orchestration	Retry; the provider may be temporarily unavailable
`AIBRAIN_1003`	504	`ORCHESTRATION_TIMEOUT`	AI orchestration timed out before completion	Reduce maxTokens or prompt complexity, then retry
`AIBRAIN_1004`	400	`CONTEXT_TOO_LARGE`	Context string exceeds maximum allowed length	Trim context to under 10,000 characters

ZAR EnsembleAIBRAIN_1100-1199

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1100`	422	`CONSENSUS_FAILED`	ZAR ensemble failed to reach consensus across 3 models	Retry or fall back to single mode
`AIBRAIN_1101`	403	`ZAR_TIER_REQUIRED`	ZAR ensemble requires Pro tier or higher	Upgrade subscription to Pro or Enterprise
`AIBRAIN_1102`	402	`ZAR_INSUFFICIENT_CREDITS`	ZAR requires 60 credits but wallet balance is insufficient	Purchase additional credits or use single mode (5-25 credits)

ConversationsAIBRAIN_1200-1299

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1200`	404	`CONVERSATION_NOT_FOUND`	Conversation ID does not exist or belongs to a different tenant	Verify conversation ID and tenant context
`AIBRAIN_1201`	409	`CONVERSATION_LOCKED`	Conversation is locked or archived	Create a new conversation or unlock the existing one
`AIBRAIN_1202`	400	`MAX_TURNS_EXCEEDED`	Conversation has reached maximum turn limit	Start a new conversation

VoiceAIBRAIN_1300-1399

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1300`	400	`INVALID_AUDIO_URL`	Audio URL is invalid or not accessible	Provide a valid, publicly accessible audio URL
`AIBRAIN_1301`	400	`UNSUPPORTED_AUDIO_FORMAT`	Audio format not supported (must be m4a, mp3, wav, ogg, or webm)	Convert audio to a supported format
`AIBRAIN_1302`	502	`STT_ERROR`	Speech-to-text service (studio-svc) returned an error	Retry; studio-svc may be temporarily unavailable
`AIBRAIN_1303`	502	`TTS_ERROR`	Text-to-speech service returned an error	Retry or set ttsResponse: false to skip TTS

Social AIAIBRAIN_1400-1499

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1400`	404	`USER_NOT_FOUND`	User ID not found for social AI operation	Verify the user ID exists in user-svc
`AIBRAIN_1401`	400	`INVALID_CONTENT_LIST`	Content list for ranking is empty or malformed	Provide at least one content item with required fields

Fraud DetectionAIBRAIN_1500-1599

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1500`	400	`INVALID_FRAUD_INPUT`	Fraud detection input data is missing required fields	Include all required fields: userId, action, metadata
`AIBRAIN_1501`	502	`FRAUD_MODEL_ERROR`	Fraud detection model returned an error	Retry; the ML model may be loading

AdminAIBRAIN_1600-1699

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1600`	403	`ADMIN_REQUIRED`	Admin role required for this operation	Use an account with admin role
`AIBRAIN_1601`	404	`MODEL_CONFIG_NOT_FOUND`	Model configuration not found	Use GET /admin/models to list available configurations
`AIBRAIN_1602`	404	`TENANT_CONFIG_NOT_FOUND`	Tenant-specific configuration not found	Create tenant config via PUT /admin/tenant-config

Quota & CreditsAIBRAIN_1700-1799

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1700`	429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded for this tenant or user	Implement exponential backoff; check Retry-After header
`AIBRAIN_1701`	402	`INSUFFICIENT_CREDITS`	Insufficient AI credits in wallet	Purchase additional credits or upgrade subscription tier
`AIBRAIN_1702`	402	`BUDGET_EXCEEDED`	Request cost exceeds x-budget-max-usd header limit	Increase budget header or reduce request complexity
`AIBRAIN_1703`	429	`QUOTA_EXCEEDED`	Monthly quota exceeded for this subscription tier	Upgrade subscription tier or wait for quota reset

AuthenticationAIBRAIN_1800-1899

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1800`	401	`UNAUTHORIZED`	Authentication required	Provide a valid JWT token in Authorization header
`AIBRAIN_1801`	403	`FORBIDDEN`	Insufficient permissions for this operation	Request required role from admin
`AIBRAIN_1802`	401	`INVALID_TOKEN`	Invalid or expired authentication token	Obtain a fresh JWT token via auth-svc

GeneralAIBRAIN_1900-1999

Code	HTTP	Name	Description	Resolution
`AIBRAIN_1900`	500	`INTERNAL_SERVER_ERROR`	Internal server error	Retry; if persistent, contact support with request_id
`AIBRAIN_1901`	503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry with exponential backoff
`AIBRAIN_1902`	504	`TIMEOUT`	Request timeout	Reduce request complexity or retry
`AIBRAIN_1903`	500	`DATABASE_ERROR`	Database operation failed	Retry; Aurora Serverless may be scaling up