Idempotency

The Idempotency middleware helps build fault-tolerant APIs. Duplicate requests—such as retries after network issues—won't trigger the same action twice on the server.

Refer to IETF RFC 7231 §4.2.2 for definitions of safe and idempotent HTTP methods.

HTTP Method Categories

Safe Methods (do not modify server state): GET, HEAD, OPTIONS, TRACE
Idempotent Methods (identical requests have the same effect as a single one): all safe methods plus PUT and DELETE

According to the RFC, safe methods never change server state, while idempotent methods may change state but remain safe to repeat.

Signatures

func New(config ...Config) fiber.Handler
func IsFromCache(c fiber.Ctx) bool
func WasPutToCache(c fiber.Ctx) bool

Examples

Import the middleware package:

import (
    "github.com/gofiber/fiber/v3"
    "github.com/gofiber/fiber/v3/middleware/idempotency"
)

Once your Fiber app is initialized, configure the middleware:

Default Config (Skip Safe Methods)

By default, the Next function skips middleware for safe methods only:

app.Use(idempotency.New())

Skip Idempotent Methods Instead

Skip all idempotent methods (including PUT and DELETE) by overriding Next:

app.Use(idempotency.New(idempotency.Config{
    Next: func(c fiber.Ctx) bool {
        // Skip middleware for idempotent methods (safe + PUT, DELETE)
        return fiber.IsMethodIdempotent(c.Method())
    },
}))

Custom Config

app.Use(idempotency.New(idempotency.Config{
    Lifetime: 42 * time.Minute,
    // ...
}))

Config

Idempotency keys are hidden in logs and error messages by default. Set DisableValueRedaction to true only when you need to expose them for debugging.

Property	Type	Description	Default
Next	`func(fiber.Ctx) bool`	Function to skip this middleware when it returns `true`; use `IsMethodSafe` or `IsMethodIdempotent`.	`func(c fiber.Ctx) bool { return fiber.IsMethodSafe(c.Method()) }`
Lifetime	`time.Duration`	Maximum lifetime of an idempotency key.	`30 * time.Minute`
KeyHeader	`string`	Header name containing the idempotency key.	`"X-Idempotency-Key"`
KeyHeaderValidate	`func(string) error`	Function to validate idempotency header syntax (e.g., UUID).	UUID length check (`36` characters)
KeepResponseHeaders	`[]string`	List of headers to preserve from original response.	`nil` (keep all headers)
DisableValueRedaction	`bool`	Disables idempotency key redaction in logs and error messages.	`false`
Lock	`Locker`	Locks an idempotency key to prevent race conditions.	In-memory locker
Storage	`fiber.Storage`	Stores response data by idempotency key.	In-memory storage

Default Config Values

var ConfigDefault = Config{
    Next: func(c fiber.Ctx) bool {
        // Skip middleware for safe methods per RFC 7231 §4.2.2
        return fiber.IsMethodSafe(c.Method())
    },

    Lifetime: 30 * time.Minute,

    KeyHeader: "X-Idempotency-Key",
    KeyHeaderValidate: func(k string) error {
        if l, wl := len(k), 36; l != wl { // UUID length is 36 chars
            return fmt.Errorf("%w: invalid length: %d != %d", ErrInvalidIdempotencyKey, l, wl)
        }

        return nil
    },

    KeepResponseHeaders: nil,

    Lock: nil, // Set in configDefault so we don't allocate data here.

    Storage: nil, // Set in configDefault so we don't allocate data here.
    DisableValueRedaction: false,
}