Status Codes and Error Tags

Last updated 2026-10-21

Every method reports through JWTAuthResult; this page lists what triggers each StatusCode and ErrorTag combination.

Mapping

StatusCode	ErrorTag	Source	Trigger
`400`	`data_missing`	`Create`	`auth` is `nil`
`400`	`data_missing`	`Revoke`	The request has no Refresh ID
`400`	`data_invalid`	`Verify`	Bad signature, `nbf` not reached, `iat` more than 5 minutes in the future, claim Refresh ID or fingerprint mismatch, JTI missing from Redis or the `EXISTS jti:` call failing
`401`	`unauthorized`	`Verify`	Neither an Access Token nor a Refresh ID
`401`	`unauthorized`	Refresh	Refresh ID absent, expired, or fingerprint mismatch
`401`	`unauthorized`	`Revoke`	Refresh ID absent or expired
`401`	`revoked`	`Verify`	The Access Token has been revoked
`401`	(empty)	Refresh	`CheckAuth` returned `false` or an error
`429`	`failed_to_update`	Refresh	The refresh lock for this Refresh ID is held, or the `SETNX` call fails
`500`	`failed_to_create`	`Create`, refresh	Refresh ID or refresh data serialization failed
`500`	`failed_to_sign`	`Create`, refresh	JWT signing failed (for example, the key is not P-256)
`500`	`failed_to_store`	`Create`, refresh, `Revoke`	Redis write failed
`500`	`failed_to_get`	`Verify`, `Revoke`	Redis read failed

"Refresh" means the Transparent Refresh triggered inside Verify; its result is returned by Verify.

The Error Field

Error is a human-readable message that may embed underlying error strings (from Redis or the JWT library); do not return it to end users or branch on it. Branch on StatusCode and ErrorTag only.
On failure the middleware returns only {"error": Error}, without ErrorTag (see Middleware).

Handling by Tag

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
}