狀態碼與錯誤標籤

最後更新 2026-10-21

所有方法以 JWTAuthResult 回報結果；本頁列出每個 StatusCode 與 ErrorTag 組合的觸發情境。

對照表

StatusCode	ErrorTag	來源	觸發情境
`400`	`data_missing`	`Create`	`auth` 為 `nil`
`400`	`data_missing`	`Revoke`	請求沒有 Refresh ID
`400`	`data_invalid`	`Verify`	簽章錯誤、`nbf` 未到、`iat` 在未來 5 分鐘以上、claim 的 Refresh ID 或指紋不符、JTI 不在 Redis 或 `EXISTS jti:` 呼叫失敗
`401`	`unauthorized`	`Verify`	沒有 Access Token 也沒有 Refresh ID
`401`	`unauthorized`	刷新	Refresh ID 不存在、已過期或指紋不符
`401`	`unauthorized`	`Revoke`	Refresh ID 不存在或已過期
`401`	`revoked`	`Verify`	Access Token 已被撤銷
`401`	（空）	刷新	`CheckAuth` 回傳 `false` 或 error
`429`	`failed_to_update`	刷新	同一 Refresh ID 的刷新鎖被占用，或 `SETNX` 呼叫失敗
`500`	`failed_to_create`	`Create`、刷新	Refresh ID 或刷新資料序列化失敗
`500`	`failed_to_sign`	`Create`、刷新	JWT 簽署失敗（例如金鑰不是 P-256）
`500`	`failed_to_store`	`Create`、刷新、`Revoke`	Redis 寫入失敗
`500`	`failed_to_get`	`Verify`、`Revoke`	Redis 讀取失敗

「刷新」指由 Verify 內部觸發的透明刷新，結果經 Verify 回傳。

Error 欄位

Error 是給人讀的訊息，內容可能包含底層錯誤字串（例如 Redis 或 JWT 函式庫的訊息），不應直接回傳給終端使用者，也不應用來做程式判斷；程式判斷一律用 StatusCode 與 ErrorTag。
中介層失敗時只回 {"error": Error}，不含 ErrorTag（見中介層）。

依標籤處理

result := auth.Verify(w, r)
if !result.Success {
	switch result.ErrorTag {
	case "revoked", "unauthorized", "":
		http.Error(w, "please sign in", http.StatusUnauthorized)
	case "failed_to_update":
		w.Header().Set("Retry-After", "1")
		http.Error(w, "retry", http.StatusTooManyRequests)
	case "data_invalid", "data_missing":
		http.Error(w, "invalid credentials", http.StatusBadRequest)
	default:
		log.Printf("go-jwt: %s", result.Error)
		http.Error(w, "internal error", http.StatusInternalServerError)
	}
	return
}