gofiber/fiber · error · ErrInvalidIdempotencyKey

invalid idempotency key

Error message

invalid idempotency key

What it means

Returned by idempotency middleware (config.go:12) when the KeyHeaderValidate function rejects the idempotency key sent in the request header (default: X-Idempotency-Key). The default validator requires the key to be exactly 36 characters (UUID length). The error is wrapped with the length mismatch detail. It fires on unsafe methods only (safe methods are skipped by the default Next function).

Source

Thrown at middleware/idempotency/config.go:12

package idempotency

import (
	"errors"
	"fmt"
	"time"

	"github.com/gofiber/fiber/v3"
	"github.com/gofiber/fiber/v3/internal/storage/memory"
)

var ErrInvalidIdempotencyKey = errors.New("invalid idempotency key")

// Config defines the config for middleware.
type Config struct {
	// Lock locks an idempotency key.
	//
	// Optional. Default: an in-memory locker for this process only.
	Lock Locker

	// Storage stores response data by idempotency key.
	//
	// Optional. Default: an in-memory storage for this process only.
	Storage fiber.Storage

	// Next defines a function to skip this middleware when returned true.
	//
	// Optional. Default: a function which skips the middleware on safe HTTP request method.
	Next func(c fiber.Ctx) bool

View on GitHub (pinned to 9a4c7e57fe)

Solutions

1. Send a valid UUID v4 in the X-Idempotency-Key header (36 chars including hyphens).
2. If your system uses a different key format, override KeyHeaderValidate with a function that accepts your format (ensure keys are still unique and unguessable).
3. Generate UUIDs client-side with a standard library (crypto/rand or github.com/google/uuid).

Example fix

// before
curl -H 'X-Idempotency-Key: 123' -X POST https://app/api/charge
// after
curl -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' -X POST https://app/api/charge

// or accept custom key format
app.Use(idempotency.New(idempotency.Config{
  KeyHeaderValidate: func(k string) error {
    if len(k) < 8 { return fmt.Errorf("%w: too short", idempotency.ErrInvalidIdempotencyKey) }
    return nil
  },
}))

// Client-side: generate a valid UUID before sending
import "github.com/google/uuid"
key := uuid.NewString() // always 36 chars
req.Header.Set("X-Idempotency-Key", key)

When it happens

Trigger: A POST/PUT/PATCH/DELETE request includes an X-Idempotency-Key header whose value is not 36 characters — e.g. a short arbitrary string, a non-UUID identifier, or a UUID without hyphens (32 chars). The default KeyHeaderValidate at config.go:67-73 checks length only.

Common situations: Client sends a numeric ID or a random short string as the idempotency key instead of a UUID; API consumers unfamiliar with the UUID requirement; a non-UUID key format used by a legacy system; omitting hyphens from a UUID.

Related errors

• csrf: referer does not match host or trusted origins
• hostauthorization: forbidden host
• missing or invalid API Key
• remote address cannot be empty
• decode SHA256 password: invalid length

AI-assisted analysis of gofiber/fiber@9a4c7e57fe (2026-08-04). Data as JSON: /data/errors/eebfeac758d15168.json. Report an issue: GitHub.