エラー

センチネルエラー

すべてのエラーは errors.Is() で判定します：

var (
    ErrInvalidConfig        = errors.New("invalid configuration")
    ErrInvalidSecretKey     = errors.New("invalid secret key")
    ErrInvalidSigningMethod = errors.New("invalid signing method")

    ErrInvalidToken          = errors.New("invalid token")
    ErrEmptyToken            = errors.New("empty token")
    ErrAlgorithmMismatch     = errors.New("token algorithm does not match configured signing method")
    ErrTokenRevoked          = errors.New("token revoked")
    ErrTokenMissingID        = errors.New("token missing ID")
    ErrTokenTypeMismatch     = errors.New("token type mismatch")
    ErrTokenExpired          = errors.New("token expired")
    ErrTokenNotValidYet      = errors.New("token not valid yet")
    ErrTokenInvalidIssuer    = errors.New("token invalid issuer")
    ErrTokenInvalidAudience  = errors.New("token invalid audience")
    ErrExpirationRequired    = errors.New("token missing expiration claim")

    ErrInvalidClaims = errors.New("invalid claims")

    ErrRateLimitExceeded = errors.New("rate limit exceeded")

    ErrBlacklistNotConfigured = errors.New("blacklist not configured")

    ErrProcessorClosed = errors.New("processor closed")
    ErrStoreClosed     = errors.New("blacklist store is closed")
)

エラー一覧

エラー	説明	errors.Is() での確認
ErrInvalidConfig	設定が無効	New()、Config.Validate()
ErrInvalidSecretKey	秘密鍵が無効	New()
ErrInvalidSigningMethod	署名メソッドが無効	New()
ErrInvalidToken	トークンが無効（署名エラーなど）	Validate()、Refresh()、ValidateInto()、RefreshInto()、Revoke()、IsRevoked()
ErrEmptyToken	トークンが空	すべてのトークン操作メソッド
ErrAlgorithmMismatch	トークンのアルゴリズムが設定と一致しない	Validate()、Refresh()、ValidateInto()、RefreshInto()
ErrTokenRevoked	トークンが失効済み	Validate()、Refresh()、ValidateInto()、RefreshInto()
ErrTokenMissingID	トークンに ID がない	Revoke()、IsRevoked()
ErrTokenTypeMismatch	トークンタイプの不一致（アクセストークンでリフレッシュを試行）	Refresh()、RefreshInto()
ErrTokenExpired	トークンの有効期限切れ	Validate()、Refresh()、ValidateInto()、RefreshInto()
ErrTokenNotValidYet	トークンがまだ有効ではない	Validate()、Refresh()、ValidateInto()、RefreshInto()
ErrTokenInvalidIssuer	発行者が一致しない	Validate()、Refresh()、ValidateInto()、RefreshInto()、Revoke()、IsRevoked()
ErrTokenInvalidAudience	オーディエンスが一致しない	Validate()、Refresh()、ValidateInto()、RefreshInto()、Revoke()、IsRevoked()
ErrExpirationRequired	RequireExpiration が有効だがトークンに exp クレームがない	Validate()、Refresh()、ValidateInto()、RefreshInto()
ErrInvalidClaims	Claims の検証に失敗	Create()、CreateRefresh()、Validate()、Refresh()、ValidateInto()、RefreshInto()
ErrRateLimitExceeded	レート制限を超過	Create()、CreateRefresh()、Refresh()、RefreshInto()
ErrBlacklistNotConfigured	ブラックリストが未設定	Revoke()
ErrProcessorClosed	Processor がクローズ済み	すべてのメソッド
ErrStoreClosed	ストアがクローズ済み	Revoke() など

シーン別分類

設定段階

エラー	発生メソッド	典型的な原因
ErrInvalidConfig	New()	複数の設定項目が不正
ErrInvalidSecretKey	New()	HMAC 秘密鍵が 32 バイト未満または弱鍵
ErrInvalidSigningMethod	New()	12 種の内蔵アルゴリズムにない

トークン検証

エラー	発生メソッド	典型的な原因
ErrEmptyToken	すべてのトークン操作メソッド	空文字列の渡し
ErrInvalidToken	Validate()、Refresh()、ValidateInto()、RefreshInto()、Revoke()、IsRevoked()	署名の不一致またはフォーマットエラー
ErrAlgorithmMismatch	Validate()、Refresh()、ValidateInto()、RefreshInto()	トークンヘッダーのアルゴリズムが設定と一致しない
ErrExpirationRequired	Validate()、Refresh()、ValidateInto()、RefreshInto()	RequireExpiration が有効だがトークンに exp クレームがない
ErrTokenExpired	Validate()、Refresh()、ValidateInto()、RefreshInto()	exp 時刻を超過
ErrTokenNotValidYet	Validate()、Refresh()、ValidateInto()、RefreshInto()	nbf 時刻にまだ達していない
ErrTokenInvalidIssuer	Validate()、Refresh()、ValidateInto()、RefreshInto()、Revoke()、IsRevoked()	iss が Config.Issuer と一致しない
ErrTokenInvalidAudience	Validate()、Refresh()、ValidateInto()、RefreshInto()、Revoke()、IsRevoked()	aud が Config.ExpectedAudience と一致しない
ErrTokenRevoked	Validate()、Refresh()、ValidateInto()、RefreshInto()	トークンがブラックリストにある
ErrTokenTypeMismatch	Refresh()、RefreshInto()	アクセストークン（token_type=access）でリフレッシュを試行
ErrInvalidClaims	Create()、CreateRefresh()、Validate()、Refresh()、ValidateInto()、RefreshInto()	ビジネス検証の失敗
ErrTokenMissingID	Revoke()、IsRevoked()	トークンに jti フィールドがない

レート制限とブラックリスト

エラー	発生メソッド	典型的な原因
ErrRateLimitExceeded	Create()、CreateRefresh()、Refresh()、RefreshInto()	ウィンドウ内のリクエスト上限を超過
ErrBlacklistNotConfigured	Revoke()	ブラックリストストアが未設定
ErrTokenMissingID	Revoke()、IsRevoked()	トークンに jti フィールドがない

ライフサイクル

エラー	発生メソッド	典型的な原因
ErrProcessorClosed	すべてのメソッド	Close() 呼び出し後に操作を継続
ErrStoreClosed	Revoke() など	ブラックリストストアがクローズ済み

---

エラー処理パターン

import "errors"

claims, valid, err := processor.Validate(tokenString)
if err != nil {
    switch {
    case errors.Is(err, jwt.ErrTokenExpired):
        // トークン有効期限切れ - ユーザーにリフレッシュを案内
    case errors.Is(err, jwt.ErrTokenRevoked):
        // トークンが失効済み - アクセスを拒否
    case errors.Is(err, jwt.ErrInvalidToken):
        // 署名が無効 - アクセスを拒否
    case errors.Is(err, jwt.ErrProcessorClosed):
        // システムエラー - Processor がクローズ済み
    default:
        // 不明なエラー
    }
}

---

エラー型

ValidationError

type ValidationError struct {
    Field   string
    Message string
    Err     error
}

フィールドレベルの検証失敗エラー。詳細は型と定数 → ValidationErrorを参照。