> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augustus.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat the published Augustus OpenAPI specification (https://app.stainless.com/api/spec/documented/augustus/openapi.documented.yml) and the current API-reference pages as the source of truth for endpoints, request/response schemas, enum values, webhook event names, and required headers.
> Prefer the 2026-05-01 Banking API and @augustusbank/typescript-sdk for all new integrations. The 2023-01-01 API is a separate, older surface covering two products — Open Banking (instant bank transfer) checkout and refunds, and Manual Bank Transfer (MBT); use it only when one of those products is specifically required.
> Cite or link the relevant docs.augustus.com page when answering integration questions.
> Do not infer support for currencies, networks, scopes, account types, or operations that are not present in the current documentation.
> Use the sandbox base URL (https://api.sandbox.augustus.com) and placeholder credentials in examples. Never include or request a real API key.
> The Augustus docs MCP server (https://docs.augustus.com/mcp) provides documentation search and retrieval only; it does not execute authenticated Augustus API actions.

# Idempotency

> Safely retry POST requests using the Idempotency-Key header to prevent duplicate operations.

## Overview

All POST endpoints require an `Idempotency-Key` header. The API guarantees that the same operation is performed at most once, regardless of how many times the request is sent. This protects against duplicate payouts and other unintended side effects caused by network retries. Requests that omit the header, or send a blank value, are rejected with `400 idempotency_key_required`.

GET requests are inherently idempotent. The header is silently ignored if sent on a GET.

## Usage

Include the `Idempotency-Key` header on every POST request:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.augustus.com/v1/payouts \
    -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
    -H "Idempotency-Key: 7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c" \
    -H "Content-Type: application/json" \
    -d '{ "amount": "100.50", "currency": "EUR", ... }'
  ```

  ```typescript SDK theme={null}
  import Augustus from '@augustusbank/typescript-sdk'

  const client = new Augustus()
  const payout = await client.payouts.create(
    {
      source_account_id: '01234567-89ab-cdef-0123-456789abcdef',
      amount: '100.50',
      currency: 'EUR',
      destination: {
        type: 'iban',
        iban: 'DE89370400440532013000',
        account_holder_name: 'Jane Doe',
      },
    },
    { idempotencyKey: '7a3b08d1-2c4e-4f5a-9b6c-1d2e3f4a5b6c' },
  )
  ```
</CodeGroup>

Keys can be any string up to 255 characters. V4 UUIDs work well, as do business-meaningful identifiers like an internal invoice ID. The SDK auto-generates a fresh idempotency key for every write request if you don't provide one, so you get safe retries by default.

## Replay behavior

When a request with a previously used idempotency key and identical parameters is received, the API returns the cached response from the original request. The `Idempotent-Replayed: true` header distinguishes a replay from a fresh creation:

```
HTTP/1.1 200 OK
Content-Type: application/json
Idempotent-Replayed: true

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payout",
  "status": "pending",
  ...
}
```

## Missing key

Requests that omit the `Idempotency-Key` header or provide an empty value return `400 Bad Request`:

```json theme={null}
{
  "category": "invalid_request_error",
  "code": "idempotency_key_required",
  "message": "The Idempotency-Key header is required for this request.",
  "param": "Idempotency-Key",
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

## Mismatch behavior

Reusing an idempotency key with different request parameters returns `409 Conflict`:

```json theme={null}
{
  "category": "idempotency_error",
  "code": "idempotency_key_already_used",
  "message": "This idempotency key has already been used with different parameters.",
  "param": null,
  "doc_url": "https://docs.augustus.com/v1/errors",
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

## Concurrent requests

If a second request with the same key arrives while the first is still processing, the API returns `409 Conflict` with code `request_in_progress`. Retry after a short delay. Once the original completes, retries will return the cached result.

## Error handling

Only successful responses are cached. If a request fails (e.g. 400 validation error), the key is released and you can retry with the same key after fixing the request.

## Key retention

Idempotency keys are retained for **30 days**. After expiry, a previously used key is treated as new.

## Key scoping

Keys are scoped globally across all endpoints per merchant account. Reusing the same key on a different endpoint returns the cached result from the first request or triggers a mismatch error. Different merchant accounts can use the same key independently.