錯誤碼

來源：backend/common/error.go。錯誤同時帶 application code + gRPC code；本頁列 application code。

沒列在這頁的錯誤一律歸 Internal (1)，使用者只會看到「Internal error」。詳細原因會被寫到 server log。

通用（0–99）

Code	名稱	HTTP 對應	含意	怎麼處理
`0`	`Ok`	200	無錯	—
`1`	`Internal`	500	內部錯誤	看 server log；通常是 bug
`2`	`NotAuthorized`	401 / 403	未認證 / 無權限	檢查登入狀態、IAM binding
`3`	`Invalid`	400	請求格式錯 / 參數不合法	看錯誤訊息修正請求
`4`	`NotFound`	404	資源不存在	確認 ID / 是否被刪
`5`	`Conflict`	409	衝突（重複名稱、版本錯位）	重新讀取後重試
`6`	`NotImplemented`	501	功能未實作	升級到含此功能的版本
`7`	`SizeExceeded`	413	Payload / 結果過大	縮小範圍；參考 `sql_result_size` 設定

DB 連線 / 執行（101–199）

Code	名稱	含意	怎麼處理
`101`	`DBConnectionFailure`	接不到目標 DB	檢查 instance host / port / credentials / 網路 / pg_hba
`102`	`DBExecutionError`	DB 端執行錯誤（SQL 失敗、 timeout）	看 task run log；多半是 SQL 本身或目標 DB 狀態問題

DB Migration（201–299）

Code	名稱	含意	怎麼處理
`201`	`MigrationSchemaMissing`	metastore migration schema 沒建好	重跑 server startup；看 startup log
`202`	`MigrationAlreadyApplied`	同版本 migration 已套用	略過或調整版本號
`203`	`MigrationOutOfOrder`	版本順序錯	補齊中間缺漏版本
`205`	`MigrationPending`	有 pending migration 未跑完	等待 / 看 server log
`206`	`MigrationFailed`	migration 執行失敗	看 server log + revision 表；可能要人工修補

Task 時機（301–399）

Code	名稱	含意	怎麼處理
`301`	`TaskTimingNotAllowed`	變更時間不允許（凍結期 / 維護窗口外）	改窗口或申請例外

Task SQL 類型（401–499）

提交 SQL 與宣告 task type 不一致時觸發：

Code	名稱	含意
`401`	`TaskTypeNotDML`	宣告 DML 但實際非 DML
`402`	`TaskTypeNotDDL`	宣告 DDL 但實際非 DDL
`403`	`TaskTypeDropDatabase`	含 `DROP DATABASE`
`404`	`TaskTypeCreateDatabase`	含 `CREATE DATABASE`
`405`	`TaskTypeDropTable`	含 `DROP TABLE`
`406`	`TaskTypeDropIndex`	含 `DROP INDEX`
`407`	`TaskTypeDropColumn`	含 `DROP COLUMN`
`408`	`TaskTypeDropPrimaryKey`	含 `DROP PRIMARY KEY`
`409`	`TaskTypeDropForeignKey`	含 `DROP FOREIGN KEY`
`410`	`TaskTypeDropCheck`	含 `DROP CHECK`

401–410 多半是 plan check 階段就會擋下；如果走到 task 層才報，代表 plan check 被人工 override。

回應結構

JSON 錯誤回應的標準格式（gRPC-gateway 轉譯）：

json

{
  "code": 3,
  "message": "invalid plan: target database not found",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        { "field": "spec.targets[0]", "description": "database not in project" }
      ]
    }
  ]
}

code 為 application code（本頁列的數字），不是 HTTP status；HTTP status 由 gateway 依下表對應：

application code 範圍	HTTP status
`0`	200
`2`	401 / 403
`3`, `7`	400 / 413
`4`	404
`5`	409
`1`, `6`, 其他	500 / 501
`101`, `102`, `2xx`, `3xx`, `4xx`	400（夾帶 application code 細節）

錯誤碼 ​

通用（0–99） ​

DB 連線 / 執行（101–199） ​

DB Migration（201–299） ​

Task 時機（301–399） ​

Task SQL 類型（401–499） ​

回應結構 ​

相關 ​

錯誤碼