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

# Idempotency

> Understanding Grid's idempotency system and implementing idempotent operations

Grid implements idempotency to ensure that operations can be safely retried without creating duplicate resources or processing the same request multiple times.

## How it works

When you make a request to Grid's API, you can include an `x-idempotency-key` header. If you retry a failed request with the same key, Grid ensures that the operation is only processed once.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Grid
    participant Database

    Client->>Grid: Request with Idempotency Key
    Grid->>Database: Check Key
    alt Key Exists
        Database-->>Grid: Return Existing Response
        Grid-->>Client: Return Cached Response
    else Key New
        Grid->>Database: Store Key
        Grid->>Grid: Process Request
        Grid->>Database: Store Response
        Grid-->>Client: Return New Response
    end
```

## Using idempotency keys

Include an `x-idempotency-key` header in your request:

```bash theme={null}
curl https://api.squads.xyz/grid/smart-accounts \
  -H "x-idempotency-key: payment_123_xyz" \
  -H "Content-Type: application/json" \
  -d '{
    "policies": {
      "authorities": [
        {
          "address": "0x123...",
          "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
        }
      ],
      "threshold": 1
    },
    "grid_customer_id": "123e4567-e89b-12d3-a456-426614174000"
  }'
```

### Key requirements

* The `x-idempotency-key` header is optional but recommended for POST requests
* Keys must be unique for each operation
* Keys are case-sensitive
* Keys can contain letters, numbers, hyphens, and underscores

### Validity periods

Most idempotency keys are valid for 24 hours. However, intent creation idempotency keys are only valid for 2 minutes. After this period, you must generate a new key for subsequent intent creation requests.

### Successful response (new request)

```json theme={null}
{
  "data": {
    "smart_account_address": "0x123...",
    "grid_user_id": "123e4567-e89b-12d3-a456-426614174000",
    "policies": {
      "authorities": [
        {
          "address": "0x123...",
          "permissions": ["CAN_INITIATE", "CAN_VOTE", "CAN_EXECUTE"]
        }
      ],
      "threshold": 1
    },
    "created_at": "2024-03-20T12:00:00Z"
  }
}
```

### Error response (invalid key)

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "timestamp": "2024-03-20T12:00:00Z",
    "details": [
      {
        "field": "x-idempotency-key",
        "code": "INVALID_IDEMPOTENCY_KEY",
        "message": "The provided idempotency key is invalid"
      }
    ]
  }
}
```