gofiber/fiber · warning

invalid idempotency key

Error message

invalid idempotency key

What it means

Returned by middleware/idempotency when the idempotency key header fails validation. The default Config.KeyHeaderValidate requires the key to be exactly 36 characters (UUID length), and the middleware wraps the failure as fmt.Errorf("%w: invalid length: %d != %d", ErrInvalidIdempotencyKey, ...). It is the package sentinel that errors.Is matches against.

Solutions

1. Send a valid 36-character UUID in the X-Idempotency-Key header on mutations.
2. If your key format differs, set Config.KeyHeaderValidate to a function that accepts your format.
3. Make sure Config.KeyHeader matches the header name your client actually sends.
4. Generate keys client-side with a UUID library and reuse the same key for retries of the same logical request.

Example fix

// before: arbitrary key
req.Header.Set("X-Idempotency-Key", "order-12345")
// after: UUID
req.Header.Set("X-Idempotency-Key", "550e8400-e29b-41d4-a716-446655440000")
// or relax the validator
idempotency.New(idempotency.Config{
  KeyHeaderValidate: func(k string) error { return nil },
})

func validUUID(s string) error {
    if len(s) != 36 { return idempotency.ErrInvalidIdempotencyKey }
    if _, err := uuid.Parse(s); err != nil { return err }
    return nil
}

if err := validate(key); err != nil {
    if errors.Is(err, idempotency.ErrInvalidIdempotencyKey) {
        // client must resend with a 36-char UUID; do not retry the same key
    }
}

When it happens

Trigger: A non-safe request carrying an X-Idempotency-Key header (default name) whose value is not 36 characters, with the default validator. Safe methods (GET/HEAD/etc.) are skipped by the default Next, so this only fires on POST/PUT/DELETE/PATCH.

Common situations: Client sends a non-UUID key (sequential id, timestamp, truncated UUID); custom KeyHeaderValidate is set but the client violates its rule; header name mismatch so an empty/garbage value is read.

Related errors

• hostauthorization: forbidden host
• add: invalid http method
• basicauth: charset must be UTF-8
• binder: custom binder not found, please be sure to enter…
• cache: failed to marshal key

AI-assisted analysis of gofiber/fiber@a105acad6c (2026-08-11). Data as JSON: /api/errors/eebfeac758d15168. Report an issue: GitHub.

Appendix: 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 a105acad6c)