> ## Documentation Index
> Fetch the complete documentation index at: https://rubie.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry mutating requests without creating duplicates.

Network issues can cause duplicate deliveries. Idempotency lets Rubie return the
original response for repeated requests, preventing duplicate credentials and runs.

## How It Works

Include a unique `Idempotency-Key` header on any mutating request:

```bash theme={null}
curl -s "https://app.rubiehq.com/api/v1/blueprints/$BLUEPRINT_KEY/trigger" \
  -X POST \
  -H "Authorization: Bearer $RUBIE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-acme-2026-07-31" \
  -d '{ ... }'
```

1. **First request** — processed normally; response stored with your key for 24 hours.
2. **Repeated request with same key + same body** — original response replayed immediately (response header `Idempotent-Replay: true`).
3. **Repeated request with same key but different body** — `409 conflict` with code `idempotency_key_reuse`.

## Supported Endpoints

| Method   | Endpoint                             |
| -------- | ------------------------------------ |
| `POST`   | `/credential-sessions`               |
| `DELETE` | `/credentials/{credentialId}`        |
| `POST`   | `/blueprints/{blueprintKey}/trigger` |

## Choosing a Key

The key should identify the **logical operation**, not the attempt — otherwise
retries generate new keys and defeat the point.

Good sources for a key:

| Operation          | Key derived from                                     |
| ------------------ | ---------------------------------------------------- |
| Credential session | The user or connection being set up                  |
| Trigger a run      | The record or job in your system that caused the run |
| Revoke             | The user or connection being disconnected            |

## Best Practices

* Keep the key stable across retries — do not change it on retry
* Never reuse a key for a different operation or different request body
* Keys are scoped to your account — the same key value is safe to reuse across different accounts

## Key Format

Any non-empty string up to 255 characters. UUIDs, `{resource}-{date}-{nonce}` patterns,
and database IDs all work well.