Idempotency keys for safe API retries

Straddle supports idempotent API requests, which means you can safely retry requests without fear of performing the same operation multiple times. This is especially important for operations that change state, like creating a payment, where duplicate requests could lead to financial discrepancies.

Overview

Idempotency is achieved by including a unique Idempotency-Key header in your HTTP requests. Straddle then uses this key to detect and prevent duplicate operations. If a request with a given key has already been processed, Straddle returns the original response without re-executing the operation.

Idempotency is currently supported for POST and PATCH requests only and requires API key authentication.

How it works

When you send a request with an Idempotency-Key header:

Straddle checks if a request with that key has been seen before.
If it’s a new key, the request is processed normally. The key and the request’s details (path, method, body hash) are stored.
If the key has been seen before:
- If the previous request with that key is still in progress, a 409 Conflict error is returned, indicating a concurrent request.
- If the previous request completed and the requests are identical, the original response is replayed with an Idempotent-Replayed: true header.
- If the idempotency key is reused for a non-identical request, a 409 Conflict error is returned, indicating that the key has been reused for a different request.
Idempotency keys are only stored for a limited period of time (~24 hours).

Using your idempotency key

To make an idempotent API request, include a unique string in the Idempotency-Key header. We require a key length of 10-40 characters. Here’s an example of how to include the Idempotency-Key header in your API requests:

curl -X POST https://sandbox.straddle.com/v1/charges \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-client-key-7890" \
  -d '{
    "amount": 100.00,
    "currency": "USD",
  }'

const apiKey = 'YOUR_API_KEY'
const idempotencyKey = 'unique-client-key-7890'

async function createCharge() {
  const res = await fetch('https://sandbox.straddle.com/v1/charges', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey
    },
    body: JSON.stringify({
      amount: 100.00,
      currency: 'USD'
    })
  })
  const json = await res.json()
  console.log(json)
}
createCharge().catch(err => console.error('Error:', err))

import requests

api_key = 'YOUR_API_KEY'
idempotency_key = 'unique-client-key-7890'

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotency_key
}

payload = {
    "amount": 100.00,
    "currency": "USD"
}

response = requests.post('https://sandbox.straddle.com/v1/charges', headers=headers, json=payload)

print(response.json())

Response headers (replayed)

When an identical request is successfully replayed, the response includes the original HTTP status code, original response headers, and the original response body, with an additional header:

HTTP/1.1 201 Created
Idempotent-Replayed: true
Content-Type: application/json

Handling idempotency errors

Straddle returns specific 409 Conflict errors in idempotency-related scenarios:

Idempotency key reused for a different request

If you send a request with an Idempotency-Key that was previously used for a different request (e.g., different path, method, or request body), you receive a 409 Conflict error.

{
  "status": 409,
  "type": "/conflict",
  "title": "Conflict",
  "detail": "Idempotency key already used for a different request."
}

Recommended Action: Generate a new, unique Idempotency-Key for each distinct logical operation.

Concurrent request in progress

If you send a request with an Idempotency-Key that is currently being processed by another request, you receive a 409 Conflict error.

{
  "status": 409,
  "type": "/conflict",
  "title": "Conflict",
  "detail": "Previous identical request currently in progress."
}

Recommended Action: Back off and retry the transaction with the same idempotency key. If the retry returns an unsuccessful status, you can safely retry the transaction with a new idempotency key.

Invalid idempotency key

If the Idempotency-Key header is supplied and does not meet the length requirements (10-40 characters), Straddle returns a 400 Bad Request error.

{
  "status": 400,
  "type": "/bad_request",
  "title": "Bad Request",
  "detail": "Validation failed",
  "items": [
    {
      "detail": "The Idempotency-Key header value is not valid."
    }
  ]
}

Recommended Action: Ensure your Idempotency-Key is present and meets the specified length requirements.

Best practices

Generate Unique Keys per Business Operation: For each distinct business operation you initiate, generate a new and unique Idempotency-Key. Do not reuse keys across different logical actions.
Use UUIDs: Universally Unique Identifiers (UUIDs) are an excellent choice for generating idempotency keys due to their high probability of uniqueness.
Handle 409 Conflicts: Implement logic in your client to properly handle 409 Conflict responses. For “key already used for a different request,” generate a new key. For “previous identical request currently in progress,” consider retrying.
Key Length: Ensure your Idempotency-Key is between 10 and 40 characters long.
Avoid Sending Same Key with Different Data: Never send the same Idempotency-Key with a different request body, path, or HTTP method. This results in a 409 Conflict error.

Next steps

Now that you are familiar with idempotent requests, it’s time to start using them. Check out our API Reference for detailed information on available endpoints and how to use them.

Fundamentals

SDKs

Customers

Bridge

Paykeys

Charges

Payouts

Funding

Payments

Embed

Idempotency keys for safe API retries

Overview

How it works

Using your idempotency key

Response headers (replayed)

Handling idempotency errors

Idempotency key reused for a different request

Concurrent request in progress

Invalid idempotency key

Best practices

Next steps

​Overview

​How it works

​Using your idempotency key

​Response headers (replayed)

​Handling idempotency errors

​Idempotency key reused for a different request

​Concurrent request in progress

​Invalid idempotency key

​Best practices

​Next steps

Overview

How it works

Using your idempotency key

Response headers (replayed)

Handling idempotency errors

Idempotency key reused for a different request

Concurrent request in progress

Invalid idempotency key

Best practices

Next steps