Idempotency

Idempotency controls whether repeating a logical request can cause another provider-side attempt or can return a retained result. Gateman does not make every authenticated HTTP request idempotent, does not guarantee exactly-once execution or delivery, and does not provide one universal duplicate ledger.

Gateman has five separate concerns:

1. Contract v1 signs the optional idempotency header so the request cannot be changed without invalidating its signature.
2. Email and SMS routes provide Gateman-managed idempotency records.
3. Credential-disclosure routes use a separate single-use request identifier.
4. Provider relays can forward provider-native idempotency mechanisms.
5. Operation accounting determines whether an accepted billable invocation consumes an operation. Accounting is not universal request deduplication.

Signed idempotency keys and Contract v1

X-GM-Idempotency-Key is optional. Its normalized value is included in the Contract v1 signing input for both HMAC-SHA256 and Ed25519 requests. Before signing, Contract v1 trims leading and trailing ASCII spaces (0x20) and tabs (0x09). A missing header, an empty value, or a value containing only those characters contributes an empty signing component. The exact signing construction, raw-body rules, timestamp, and encoding are defined in Contract v1.

Signing this header does not create a server-side idempotency record. It only binds the normalized value to the authenticated request. Duplicate suppression exists only where the selected capability implements it.

Email and SMS validate a supplied non-empty key in their own route-specific idempotency stores. Their current rules trim the key, reject an empty key, reject keys over 255 bytes, and reject ASCII control characters. These rules are capability rules, not a universal Contract v1 validation rule. Do not rely on duplicate physical HTTP headers; send one canonical header value.

Capability coverage

Email idempotency

The email routes are:

• POST /send/ses
• POST /send/postmark
• POST /send/resend

Email idempotency is optional. When supplied, a key is scoped by the application and email provider. The request fingerprint includes the selected environment and normalized provider payload. Environment therefore participates in conflict detection but does not create separate email key namespaces: reusing a key for the same application and provider in another environment can produce 409 with idempotency_key_payload_conflict.

The normal outcomes are:

Completed successful and definite failed results are retained for 15 minutes. Email idempotency replays the stored Gateman JSON result, not the original HTTP response status or headers. Successful results replay with HTTP 200, while retained failures replay with HTTP 409. Original response headers, including Retry-After, are not preserved.

Email admission is provider-aware. For production sends, provider-bound concurrency is admitted before operation accounting. A definitive provider concurrency rejection therefore consumes no operation and releases the owned claim for a legitimate retry. A monthly allowance rejection or accounting failure also occurs before provider execution, consumes no operation, and releases the owned claim. Staging and development capture bypass provider concurrency and reserve an operation immediately before capture; an accepted capture consumes one operation.

After admission, an accepted provider or capture operation remains billable even when the provider rejects it, times out, or its outcome becomes indeterminate. Provider-started or uncertain claims remain protected. Gateman does not automatically retry email sends. SES, Postmark, and Resend retain their distinct request formats and provider error classifications; SES also uses Gateman-controlled sender identity as a security boundary. SES SDK automatic retries are disabled so Gateman's idempotency and uncertainty model is not hidden behind an additional SDK retry.

SMS idempotency

The SMS routes are:

• POST /twilio/sms/send
• POST /telnyx/sms/send
• POST /aws/sms/send

SMS idempotency is optional. A key is scoped by application, provider, and environment. The fingerprint includes the provider, environment, and request payload. Unlike email, environments are independent SMS idempotency namespaces: the same key can be used separately for production, staging, and development, subject to each route's request requirements.

Successful results and definite provider failures are retained and replayed for the active retention period. SMS replays the stored HTTP status, body, and selected response headers. A changed payload under the same scoped key returns 409 with idempotency_key_payload_conflict. A duplicate whose first request is still in_progress, or whose provider outcome is uncertain, returns 409 with sms_send_indeterminate.

Provider-bound concurrency is checked before SMS operation accounting. A definitive concurrency rejection returns the route's 429 or 503 response, consumes no operation, and releases the current claim so the same key can be retried. If accounting rejects the request because the monthly allowance is exhausted, or accounting is unavailable, no provider request has started, no operation is consumed, and the current claim is released. A legitimate retry with the same key can then claim it again.

Once an SMS operation is accepted and provider execution may have started, the claim remains protected. Provider timeouts, transport failures, and uncertain provider results do not prove that no SMS was sent. Do not switch to a new key unless the application deliberately accepts the possibility of a duplicate.

Staging and development SMS requests are captured locally rather than sent to Twilio, Telnyx, or AWS. An accepted capture consumes one operation and its successful result can be replayed through the SMS idempotency record. The provider-native response contracts are otherwise unchanged.

Retention, unresolved operations and recovery

The documented retention period for supported email and SMS send results is 15 minutes.

Terminal results can expire. After expiry, the same key may be claimed for a new operation, and that new operation can consume another operation allowance. Expiry is not a guarantee that every key is reusable:

• Email can recover an expired in_progress claim only when its execution state shows that provider execution was not started. A provider-admitted or provider-started claim remains protected when its outcome is unresolved.
• Email unknown results and SMS indeterminate results remain protected; they are not physically reclaimed merely because the replay window elapsed.
• SMS protects an unresolved in_progress claim; provider-started or indeterminate outcomes must be treated as potentially executed.

Operation-accounting recovery does not reconcile provider execution or email/SMS idempotency records. A timeout is not evidence that the provider rolled back a mutation or message.

Credential-request replay protection

POST /secrets/get and POST /db/get require a separate header:

X-GM-Credential-Request-ID: 0123456789abcdef0123456789abcdef

The value must be exactly 32 lowercase hexadecimal characters. It is included in Contract v1 signing input and is claimed once for the authenticated application across both credential-retrieval routes. Claims are retained for 11 minutes. Reuse returns 409; a legitimate subsequent attempt requires a fresh identifier and a fresh signature.

Credential responses are never replayed from an idempotency cache. A request identifier may remain consumed even if a later stage of the request fails. This protection is distinct from X-GM-Idempotency-Key, which is optional and does not make ordinary authenticated requests single-use. Do not put credential values or storage details in application logs.

Provider-native idempotency

Provider relays do not share a universal Gateman duplicate ledger. Where a relay contract supports a provider-native mechanism, Gateman validates and forwards it; the provider defines its meaning, scope, retention, and replay behavior.

An accepted Gateman relay invocation ordinarily consumes its own operation, even when the external provider recognizes the forwarded request as a duplicate. Gateman does not automatically deduplicate relay calls and does not automatically retry provider mutations. See the individual Stripe, Square, PayPal, AWS, and Cloudflare references for request-specific rules.

Idempotency and operation accounting

Idempotency and accounting answer different questions: idempotency controls whether a logical send is attempted again, while accounting controls whether an accepted billable invocation consumes an operation.

Rejected authentication, validation, credential-request replay, and pre-reservation admission requests do not consume a billable operation. Once a billable operation is accepted, provider failure does not make it free. See Operation Accounting for the complete allowance and enforcement contract.

Retry guidance

• Retry a definitive pre-provider rejection when the response permits it. For supported email and SMS sends, the same key can be retried after Gateman releases the rejected claim.
• Replay an exact retained terminal result rather than starting a new logical send.
• Do not blindly retry mail_send_indeterminate or sms_send_indeterminate. A provider may already have accepted the message.
• A new idempotency key means a new logical send and can duplicate an earlier uncertain send.
• After terminal retention expires, decide explicitly whether a new attempt is safe; do not assume the previous provider execution did not occur.
• For /secrets/get and /db/get, generate a new credential request ID and signature for every legitimate retry.
• For provider relays, use the provider-native identifier required by the selected provider operation when available. Gateman will not add one or retry the mutation for you.
• A transport timeout proves only that the client did not receive a completed response. It does not prove provider failure. Respect applicable Retry-After headers for rate limits, but do not convert a provider rate limit or timeout into a blind duplicate mutation.

The official PHP, Node.js, Python, and Go clients do not automatically retry Gateman requests.

Related references

• Contract v1
• Authentication and signing
• Errors and responses
• Operation Accounting
• Rate limits and concurrency
• Environments
• Send email
• Send SMS