Idempotency

Send an Idempotency-Key with every POST so a retried request never creates a second message.

Applies to

Safe retry

1// Placeholder: Fernway is a fictional API.
2import { randomUUID } from "node:crypto"
3 
4const key = randomUUID() // store it with your own record
5 
6const message = await fernway.messages.create(
7  { to: "+15555550123", channel: "sms", body: "Your code is 482913" },
8  { idempotencyKey: key }
9)
10 
11// Retrying with the same key returns the original message
12// instead of sending a second one.

Why it matters

Networks fail halfway. If a request times out you cannot tell whether Fernway received it. Sending the same Idempotency-Key on the retry makes the call safe: the first result is replayed and no duplicate message goes out.

Rules

Use a unique key per logical operation, such as a UUID stored with your order or user action.
Keys are kept for 24 hours. After that the same key starts a new request.
Reusing a key with a different body returns 409 idempotency_conflict.
GET and DELETE are already idempotent and ignore the header.

SDK behaviour

The official SDKs generate a key for you when they retry automatically. Pass your own key when the retry might come from a different process.

Placeholder API

Fernway is a fictional product used to show how this template works. Replace these docs with your own in the CMS.

← Rate limits

Versioning policy →