Idempotency

The Flowbrite API requires idempotency for all endpoints that perform operations with side effects (e.g. creating a payment). This ensures that duplicate resources are not created if the same request is sent more than once.

How It Works

Idempotency allows clients to safely retry requests without unintended consequences. For example, if a network error prevents a response from being received, the client may not know whether the request was processed or lost. By using idempotency, you ensure that retrying the request does not result in duplicate operations.

To make an idempotent request, include the X-IDEMPOTENCY-KEY header with a unique value that identifies that specific request.

If you try to call an endpoint that requires idempotency without providing the X-IDEMPOTENCY-KEY header or providing an empty header value, you will receive a 400 Bad Request response.

{
  "error": {
    "status": 400,
    "code": "api.common.missingIdempotencyKey",
    "message": "The endpoint '{path}' requires an X-IDEMPOTENCY-KEY header"
  }
}

Key Points

• Idempotency is mandatory for all side-effecting operations.
• Use the X-IDEMPOTENCY-KEY header to uniquely identify each request.
• Keys expire after 15 minutes; reusing a key after that window will result in the request being processed again.

If a request with the same key is received within 15 minutes, you will receive a 409 Conflict response.

{
  "error": {
    "status": 409,
    "code": "api.common.reusedIdempotencyKey",
    "message": "The X-IDEMPOTENCY-KEY header value 'FLWBRT-01JXWKXK5E93TPC0HV2105T0ND' has already been used in the last 900 seconds"
  }
}