Idempotency-Key Header Versus OAuth Signature: Deduplication Trade-offs for Twitter API Writes

Idempotency Guarantee for Twitter API Writes

Twitter guarantees idempotency primarily through the Idempotency-Key header, not through OAuth request signatures. Relying on an identical OAuth signature for deduplication is not supported by documented platform behavior.

Confirmed Facts and Constraints

• Idempotency is explicitly supported for POST, PUT, and DELETE endpoints.
• The server-side deduplication guarantee for any given Idempotency-Key is strictly limited to 24 hours.
• The Idempotency-Key must be unique per intended operation and adhere to a 255-character limit.

Handling Long-Term Idempotency

For operations requiring guaranteed exactly-once semantics beyond the 24-hour window, clients must implement their own application-level state management, such as persisting the successful Idempotency-Key alongside the resulting resource ID in their own durable store. Key rotation must occur when the 24-hour window expires for that specific logical operation.

Addressing Specific Questions

1. Idempotency key reuse across endpoint variants is dependent on the specific API implementation, but the 24-hour server guarantee applies universally to the key itself. Key rotation is mandatory past 24 hours.
2. The absence of an Idempotency-Key header does not guarantee silent duplicate processing; however, the platform documentation does not specify observable indicators for accidental duplication outside the key mechanism.
3. OAuth 1.0a request signatures cannot reliably map to idempotency keys as this violates documented platform constraints.

To proceed safely, ensure your retry logic uses a new, unique Idempotency-Key if the original attempt occurred over 24 hours ago.