Idempotency Key

All POST APIs require idempotency to guarantee safe retries and prevent duplicate operations. You must include an Idempotency-Key header with a unique value for each new operation.

What is Idempotency?

Idempotency ensures that if a request is retried (due to network errors, client timeouts, or unexpected failures), the system can detect the duplication and return the same response without performing the operation again. This prevents accidental creation of duplicate resources.

The Idempotency-Key acts as an external identifier that creates a one-to-one binding with the entity created in our system, allowing you to:

Check if a resource was successfully created after a network timeout
Safely retry failed requests without creating duplicates
Query existing resources using your own tracking identifier

How It Works

Include a Unique Key: Add an Idempotency-Key header with a unique value (typically a UUID) to every POST request
24-Hour Window: The system guarantees idempotent behavior for 24 hours after the initial request
Same Key, Same Response: Any subsequent request with the same Idempotency-Key within 24 hours will return the original response with no side effects or duplicated operations
Expired Keys: After 24 hours, reusing the same Idempotency-Key will result in a 409 Conflict error

When to Use Idempotency Keys

Required: All POST requests (create operations)
Not Required: GET, PUT, PATCH, or DELETE requests (these methods are naturally idempotent)

Best Practices

Use UUIDs: Generate a unique UUID (v4) for each new operation
Store Keys: Save the UUID in your database to track request state
Reuse for Retries: Use the same UUID when retrying a failed request
One Key per Operation: Never reuse idempotency keys across different operations

Example Usage

curl -X POST https://sandbox-api.1money.com/v1/portfolios/{portfolio_id}/external-accounts \\
  -H \"Content-Type: application/json\" \\
  -H \"X-Api-Key: your-api-key\" \\
  -H \"Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000\" \\
  -d '{
    \"network\": \"US_FEDWIRE\",
    \"holder_name\": \"TechStart Holdings LLC\",
    \"currency\": \"USD\",
    \"country_code\": \"USA\",
    \"account_number\": \"4447891623\",
    \"institution_id\": \"021000021\",
    \"institution_name\": \"JPMorgan Chase Bank, N.A.\"
  }'

Retrieving Resources by Idempotency Key

After creating a resource, you can retrieve it using the idempotency key:

curl -X GET \"https://sandbox-api.1money.com/v1/portfolios/{portfolio_id}/external-accounts?idempotency_key=550e8400-e29b-41d4-a716-446655440000\" \\
  -H \"X-Api-Key: your-api-key\"

Error Responses

409 Conflict: Idempotency key already exists (either the resource was created, or the key expired and was reused)
400 Bad Request: Missing or invalid idempotency key format