{"id":"eebfeac758d15168","repo":"gofiber/fiber","slug":"invalid-idempotency-key","errorCode":null,"errorMessage":"invalid idempotency key","messagePattern":"invalid idempotency key","errorType":"validation","errorClass":"ErrInvalidIdempotencyKey","httpStatus":null,"severity":"error","filePath":"middleware/idempotency/config.go","lineNumber":12,"sourceCode":"package idempotency\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/gofiber/fiber/v3\"\n\t\"github.com/gofiber/fiber/v3/internal/storage/memory\"\n)\n\nvar ErrInvalidIdempotencyKey = errors.New(\"invalid idempotency key\")\n\n// Config defines the config for middleware.\ntype Config struct {\n\t// Lock locks an idempotency key.\n\t//\n\t// Optional. Default: an in-memory locker for this process only.\n\tLock Locker\n\n\t// Storage stores response data by idempotency key.\n\t//\n\t// Optional. Default: an in-memory storage for this process only.\n\tStorage fiber.Storage\n\n\t// Next defines a function to skip this middleware when returned true.\n\t//\n\t// Optional. Default: a function which skips the middleware on safe HTTP request method.\n\tNext func(c fiber.Ctx) bool\n","sourceCodeStart":1,"sourceCodeEnd":30,"githubUrl":"https://github.com/gofiber/fiber/blob/9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c/middleware/idempotency/config.go#L1-L30","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Send a valid UUID v4 in the X-Idempotency-Key header (36 chars including hyphens).","If your system uses a different key format, override KeyHeaderValidate with a function that accepts your format (ensure keys are still unique and unguessable).","Generate UUIDs client-side with a standard library (crypto/rand or github.com/google/uuid)."],"exampleFix":"// before\ncurl -H 'X-Idempotency-Key: 123' -X POST https://app/api/charge\n// after\ncurl -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' -X POST https://app/api/charge\n\n// or accept custom key format\napp.Use(idempotency.New(idempotency.Config{\n  KeyHeaderValidate: func(k string) error {\n    if len(k) < 8 { return fmt.Errorf(\"%w: too short\", idempotency.ErrInvalidIdempotencyKey) }\n    return nil\n  },\n}))","handlingStrategy":"validation","validationCode":"// Client-side: generate a valid UUID before sending\nimport \"github.com/google/uuid\"\nkey := uuid.NewString() // always 36 chars\nreq.Header.Set(\"X-Idempotency-Key\", key)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always send a UUID v4 (36 chars) as the idempotency key.","If using a custom key format, override KeyHeaderValidate to match.","Reuse the same key for retried requests to get idempotent behavior."],"tags":["idempotency","configuration","headers","api"],"analyzedSha":"9a4c7e57fe0b080a04235d28a4b0d2b4b353d58c","analyzedAt":"2026-08-04T21:44:03.395Z","schemaVersion":2}