Idempotency key generator

Generate a key for one logical operation

An idempotency key lets a supporting server recognize a retry of an operation it has already processed. Generating an identifier is only one part of that workflow: the receiving API must explicitly support deduplication, and your client must keep the same key for retries.

1. Choose a Format. UUID v4 creates random identifiers; ULID includes a sortable timestamp; Prefixed random adds your prefix to a lowercase ULID. Enter How many keys for these formats, from 1 to 200.
2. For repeatable keys, choose Derived from slug + URL (deterministic) and enter one destination URL per line, or slug | URL. Each non-empty row produces a key; this mode uses the rows rather than How many keys and accepts up to 2,000 rows.
3. Use Prefix for either prefixed or derived keys. Only letters, numbers, underscores and hyphens are retained, up to 20 characters; an empty prefix falls back to link.
4. Select Generate and review the keys, source rows and any duplicate warning. Select Copy all keys, then store each key with its operation before sending a request. Reuse that stored key when retrying the same operation.

Example: stable keys for two link jobs

Format: Derived from slug + URL (deterministic)
Prefix: launch

product-a | https://example.com/products/a
product-b | https://example.com/products/b

Each result begins with launch_ followed by 32 hexadecimal characters. Repeating the same row with the same prefix returns the same key. Repeating a row twice in one batch marks the later occurrence as a duplicate. Changing the prefix creates a different key namespace.

What deterministic means in this tool

For a valid URL, the tool lowercases the optional slug, normalizes the URL with the URL parser, joins them with a pipe, and takes the first 32 hexadecimal characters of a SHA-256 hash. A row that cannot be parsed as a URL is hashed as trimmed text. It does not inspect or hash a complete HTTP request body.

Keep different logical jobs distinct. Two operations with the same slug and destination derive the same key even if some other request field differs. For a new operation with identical content, use a separate scope or a new stored random key. Hashing is not encryption; a derived key can still reveal that the same input was used.

Using a key with an API

Read the receiving API’s rules for the header name, allowed key length, retry window and behavior when request parameters change. Send the same parameters and key for a retry. A new random key on every attempt defeats deduplication. A key does not replace authentication and is not a password.

ShortFreeURL’s link API does not accept an Idempotency-Key header. Store the chosen domain, slug and returned link ID with each operation. A taken explicit slug returns HTTP 400; duplicate-destination detection can return HTTP 409 with the existing id and path under duplicate. Read the existing link and verify its domain, path and destination before treating the operation as complete. Do not assume this behavior applies to another API.

Privacy and storage

Key generation happens on the ShortFreeURL server. Derived-mode rows and prefixes are submitted with the form, so use non-sensitive examples and omit credentials or private URL tokens. Keep production key-to-operation records in your own application. Follow the receiving API’s documented retention period rather than assuming keys remain valid forever.

Reference

• Example of API-specific rules: Stripe idempotent requests

Useful next steps

• Plan retry delays with backoff
• Generate ShortFreeURL API request snippets
• Read the developer documentation