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

Tool-Use Error Codes

Returned by the Gateway when a request with tools fails validation or the provider rejects the tool-call round-trip. These errors use OpenAI's error envelope shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "tool_schema_invalid",
    "message": "tools[0].function.parameters must have type:\"object\" at the root",
    "param": "tools[0].function.parameters"
  }
}

Code	Status	When it fires
`tool_schema_invalid`	400	A tool's `parameters` is malformed, missing `type:"object"`, or fails name pattern.
`tool_choice_invalid`	400	`tool_choice` is malformed or references a tool not in `tools[]`.
`tool_call_id_mismatch`	400	A `role:"tool"` message's `tool_call_id` does not match any prior assistant `tool_calls[].id`.
`tool_unsupported_for_model`	400	The requested model cannot use tools (e.g. `deepseek-reasoner`, `deepseek-r1`).
`tool_call_invalid_arguments`	400	`strict:true` schema validation failed after retries.
`tool_provider_error`	502	Upstream provider errored mid-call. Wraps the provider's message.

During streaming, mid-response errors are sent as:

data: {"error":{"type":"server_error","code":"tool_provider_error","message":"..."}}

data: [DONE]

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

On this page