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:

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.