All API errors follow a consistent format.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Error Code Reference

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication
`INVALID_API_KEY`	401	API key is invalid or expired
`FORBIDDEN`	403	Access denied to this resource
`BAD_REQUEST`	400	Malformed request
`MISSING_REQUIRED_FIELD`	400	Required field not provided
`INVALID_MODEL`	400	Unknown or unsupported model
`INVALID_MESSAGE_LENGTH`	400	Message exceeds 2000 characters
`STREAMING_REQUIRED`	400	Fight mode requires streaming
`GUARDRAIL_BLOCKED`	400	Request blocked by guardrails (PII, content moderation)
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`MODEL_UNAVAILABLE`	503	Model temporarily unavailable
`INTERNAL_ERROR`	500	Server error

Common Errors

Authentication Error

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Provide a valid API key."
  }
}

Solution: Include your API key in the Authorization header.

Invalid Model

{
  "error": {
    "code": "INVALID_MODEL",
    "message": "Invalid model: unknown-model",
    "details": {
      "requestedModel": "unknown-model",
      "availableModels": ["claude", "gpt", "grok", "gemini", "deepseek", "kimi", "mistral", "llama", "minimax"]
    }
  }
}

Solution: Use a valid model ID from the available models list.

Rate Limit Exceeded

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again later.",
    "details": {
      "retryAfter": 60
    }
  }
}

Solution: Wait for the specified retry time before making another request.

Missing Required Field

{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Missing required field: messages",
    "details": {
      "field": "messages"
    }
  }
}

Solution: Include all required fields in your request.

Streaming Required (Fight Mode)

{
  "error": {
    "code": "STREAMING_REQUIRED",
    "message": "Fight mode requires streaming. Set \"stream\": true or omit the stream parameter. Non-streaming fight mode has been deprecated.",
    "details": {
      "suggestion": "Remove \"stream\": false or set \"stream\": true"
    }
  }
}

Solution: Remove "stream": false from your request, or set "stream": true. Fight mode only supports streaming responses.

Error Codes