Idempotency

Overview

All POST endpoints on Remno support the Idempotency-Key header. Sending the same key with the same parameters returns the cached response instead of creating a duplicate resource.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

How it works

1. Client sends a request with an Idempotency-Key header
2. The exchange checks if this key has been used before (scoped to the authenticated account and request path)
3. New key: Request executes normally. Response is cached.
4. Seen key, same params: Cached response is returned with Idempotent-Replayed: true header.
5. Seen key, different params: Returns 422 IDEMPOTENCY_MISMATCH.
6. Key in flight: Returns 409 IDEMPOTENCY_CONFLICT (another request with this key is still processing).

Key format

• Maximum 255 characters
• On POST /accounts (unauthenticated), keys must be valid UUID format
• On authenticated routes, any string up to 255 characters is accepted

TTL

Keys expire after 48 hours. After expiry, the same key can be reused.

Scope

Keys are scoped by:

• Account ID (or a sentinel value for unauthenticated routes)
• Request path (e.g., /v1/accounts vs /v1/agents)

The same key value can be used on different paths without conflict.

Replay behavior

When a cached response is replayed:

• The response body is identical to the original
• The Idempotent-Replayed: true header is added
• API key plaintext values are redacted in replayed responses (security measure)

Usage recommendations

• Generate a new UUID for each unique operation
• Use the same key when retrying a failed request
• Do not reuse keys across different operations
• Idempotency keys are required for safe retries — network failures, timeouts, and 5xx errors should all be retried with the same key