錯誤碼

Hakila Gateway 的錯誤回應為 JSON：

{
  "error": {
    "message": "Invalid or disabled API key.",
    "code": 401
  }
}

code 與 HTTP status 相同。

常見狀態碼

HTTP	情境
`400`	請求 body 不是有效 JSON、缺少必要欄位、模型已停用或未被允許、不帶前綴的名稱對應到多個模型、`model` 為 `auto`、`provider` 偏好無效，或該模型不支援這個端點
`401`	缺少 Authorization、金鑰無效／停用、已過期，或金鑰指派的人員已停用（見 SCIM 自動佈建）
`402`	組織儲值餘額用盡，或 API Key／人員／單位／組織預算超標
`403`	組織的供應商限制排除了提供這個模型的所有供應商
`404`	模型不在平台目錄
`502`	找不到可用的上游 Provider Key、`hakila/auto` 無法選路，或其他 Gateway 轉發失敗
`503`	模型目前沒有可用的供應商
`504`	上游在首字元逾時（預設 30 秒）內未回傳第一個位元組

{
  "error": {
    "message": "Missing Authorization header. Expected: Bearer <api key>",
    "code": 401
  }
}

model 不在平台目錄（包含不帶前綴、目錄裡也沒有同名模型的名稱）：

{
  "error": {
    "message": "找不到模型 'gpt-9'。可用的模型 id 請見 GET /v1/models。",
    "code": 404
  }
}

不帶前綴的名稱對應到多個開發商的模型時，回 400 並列出候選，請改寫完整 id：

{
  "error": {
    "message": "模型名稱 'gpt-oss-120b' 對應到多個模型：openai/gpt-oss-120b、example/gpt-oss-120b。請指定完整的模型 id。",
    "code": 400
  }
}

model 為 auto 時一律回 400（模型名稱 'auto' 不明確，請指定完整的模型 id，例如 hakila/auto。）。

指定的 model 已停用，或未通過組織 ∩ API Key 允許清單：

{
  "error": {
    "message": "模型 'openai/gpt-5.6-sol' 未被此組織允許。",
    "code": 400
  }
}

其他可能文案：模型 '…' 不在允許清單中。、模型 '…' 目前未開放使用。、模型 '…' 未被此 API Key 允許。、hakila/auto 沒有符合允許清單的候選模型。

當組織儲值餘額用盡（優先檢查），或 API Key／人員／單位／組織預算超標：

{
  "error": {
    "message": "Organization credit balance exhausted.",
    "code": 402
  }
}

其他層級可能回傳 API key budget exceeded.、Person budget exceeded.、Unit budget exceeded.、Organization budget exceeded.。

組織設定了供應商限制，且提供這個模型的供應商全部被排除：

{
  "error": {
    "message": "組織的供應商限制不允許任何提供模型 'anthropic/claude-opus-5' 的供應商。",
    "code": 403
  }
}

{
  "error": {
    "message": "Provider 'openai' 尚未設定 API 金鑰。請確認 Secret Manager、ProviderKeys 或 Providers:openai:ApiKey。",
    "code": 502
  }
}

有符合允許清單的候選，但都沒有上游金鑰時：

{
  "error": {
    "message": "hakila/auto 找不到可用的上游供應商金鑰。請先在 BYOK 或平台金鑰中填入至少一組金鑰。",
    "code": 502
  }
}

{
  "error": {
    "message": "上游在 30 秒內沒有回應第一個位元組。",
    "code": 504
  }
}

上游供應商本身回傳的非 2xx 錯誤，會盡可能原樣轉發其 status 與 body。