Idempotency

Some POST APIs require idempotency to guarantee safe retries and prevent duplicate operations. Check the endpoint reference to determine whether an Idempotency-Key is required for a specific 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 without performing the operation again. This prevents accidental creation of duplicate resources.

When an endpoint supports idempotency, 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

1. Include a Unique Key: Add an Idempotency-Key header with a unique value (typically a UUID) when the endpoint requires it
2. Reuse for Retries: Reuse the same key only when retrying the same logical operation

When to Use Idempotency Keys

• Required: Endpoints that explicitly document the header as required
• Other Endpoints: Follow the endpoint reference; do not infer support from the HTTP method

Best Practices

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

Example Usage

curl -X POST https://api.sandbox.1money.com/v1/customers/{customer_id}/external-accounts \\
  -H \"Content-Type: application/json\" \\
  -H \"Authorization: Bearer {API-KEY}\" \\
  -H \"Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000\" \\
  -d '{
    \"network\": \"US_FEDWIRE\",
    \"account_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 an external account, you can retrieve it using the idempotency key:

curl -X GET \"https://api.sandbox.1money.com/v1/customers/{customer_id}/external-accounts?idempotency_key=550e8400-e29b-41d4-a716-446655440000\" \\
  -H \"Authorization: Bearer {API-KEY}\"

Error Responses

For the external account example above:

• 409 Conflict: Idempotency key already exists or identical banking details were detected
• 400 Bad Request: Missing or invalid idempotency key format