錯誤代碼 - Runbase Docs

已知 API 錯誤會返回具有以下結構的 JSON 主體：

{
  "error": {
    "message": "Human-readable description",
    "code": "error_code"
  }
}

錯誤參考

400 錯誤請求

代碼	原因	修正方式
`invalid_json`	請求主體不是有效的 JSON	檢查你的 JSON 語法
`missing_model`	`model` 欄位缺失或不是字串	在你的請求主體中包含 `"model": "provider/name"`
`missing_input`	`input` 欄位缺失或不是物件	在你的請求主體中包含 `"input": {...}`
`invalid_input`	輸入不符合模型的 schema	查看模型的 API 參考以了解必填欄位和有效值
`model_not_found`	模型 ID 不符合任何可用模型	請參閱模型頁面以取得有效的模型 ID

401 未授權

代碼	原因	修正方式
`missing_api_key`	沒有 `Authorization` header 或格式錯誤	在你的請求中包含 `Authorization: Bearer sk-...`
`invalid_api_key`	Key 無效、已停用或已過期	建立新的 key，或在 Settings → API Keys 中重新啟用現有 key

402 需要付款

代碼	原因	修正方式
`insufficient_balance`	你的餘額不足以建立此次 run	在 Settings → Credits 中為你的餘額儲值

403 禁止存取

代碼	原因	修正方式
`api_key_spend_limit_exceeded`	已達到此 key 的終身支出上限	在 Settings → API Keys 中提高支出上限
`ip_not_allowed`	你的 IP 不在此 key 的白名單中	將你的 IP 加入此 key 的允許清單，或移除白名單

429 請求過多

代碼	原因	修正方式
`RATE_LIMITED`	在短時間窗口內請求過多	等待後重試。請參閱速率限制
`USAGE_EXCEEDED`	此 key 的使用配額已耗盡	聯絡支援或建立新的 key

404 找不到

代碼	原因	修正方式
`run_not_found`	你的帳戶沒有此 ID 的 run	檢查 run ID 是否正確，且是否是使用此 API key 建立的

500 伺服器內部錯誤

我們這邊發生了未預期的錯誤。如果這種情況持續發生，請聯絡 support@runbase.net。

在程式碼中處理錯誤

response=$(curl -s -w "\n%{http_code}" https://runbase.net/api/v1/runs \
  -H "Authorization: Bearer $RUNBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/nano-banana-2", "input": {"prompt": "test"}}')
 
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)
 
if [ "$http_code" -ne 201 ]; then
  echo "Error $http_code: $(echo $body | jq -r '.error.message')"
fi

對於 429 錯誤，請實作指數退避——重試前先等待 1 秒，然後 2 秒，再 4 秒。