Skip to main content
Version: v2.x


Idempotency middleware for Fiber allows for fault-tolerant APIs where duplicate requests — for example due to networking issues on the client-side — do not erroneously cause the same action performed multiple times on the server-side.

Refer to for a better understanding.


func New(config ...Config) fiber.Handler


Import the middleware package that is part of the Fiber web framework

import (

After you initiate your Fiber app, you can use the following possibilities:

Default Config


Custom Config

Lifetime: 42 * time.Minute,
// ...


// Config defines the config for middleware.
type Config struct {
// 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

// Lifetime is the maximum lifetime of an idempotency key.
// Optional. Default: 30 * time.Minute
Lifetime time.Duration

// KeyHeader is the name of the header that contains the idempotency key.
// Optional. Default: X-Idempotency-Key
KeyHeader string
// KeyHeaderValidate defines a function to validate the syntax of the idempotency header.
// Optional. Default: a function which ensures the header is 36 characters long (the size of an UUID).
KeyHeaderValidate func(string) error

// KeepResponseHeaders is a list of headers that should be kept from the original response.
// Optional. Default: nil (to keep all headers)
KeepResponseHeaders []string

// 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

Default Config

var ConfigDefault = Config{
Next: func(c *fiber.Ctx) bool {
// Skip middleware if the request was done using a safe HTTP method
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.