Idempotency

A request method is considered idempotent if the intended effect of multiple identical requests with that method is the effect of a single request.

The Brex API supports idempotency using an Idempotency-Key header to protect against duplicate operations. For most endpoints, the header is optional but we highly recommend that you set one. For endpoints where erroneous duplicate processing would be especially bad, such as Create transfer and Create card, we require an idempotency key.

Generate and store idempotency keys

Your application must not provide identical idempotency keys for different requests. We suggest using random strings with sufficient entropy to avoid collisions like V4 UUIDs.

Your application should store these keys so that semantically identical requests are sent with the same idempotency keys.

Example

Here’s an example of why idempotency keys are important. Imagine the following sequence of events:

1. Your application sends a request to create a $1,000 wire transfer.
2. Brex receives and processes the request.
3. Due to high network congestion, before Brex responds to your application, the request times out.
4. Believing the initial request failed, your application retries the request later.

If your application’s request included the same idempotency key for both requests, Brex will identify the second request as a duplicate and ignore it. However, if your application had omitted the idempotency key, or provided two different idempotency keys, Brex would process the second request, creating a $1,000 wire transfer which you did not intend to initiate.

Other notes

• All POST and PUT requests accept idempotency keys.
• Sending idempotency keys in GET and DELETE requests has no effect and should be avoided–these requests are idempotent by definition.
• Some requests may have additional idempotency due to the product behavior. For example, creating another user with the same email would be idempotent but return an error message.