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

# Idempotency & Retries

> How to safely handle network timeouts and retries in the Travomatrix B2B API.

When making requests that perform financial operations (like creating a booking or confirming a cancellation), it's critical to ensure that a request isn't processed more than once. Network issues can sometimes result in a timeout while the server is still processing your request.

## The Idempotency-Key

Travomatrix supports the `Idempotency-Key` header for the following endpoints:

* `POST /booking/create`
* `POST /booking/cancel/confirm`

An idempotency key is a unique string (we recommend a UUID v4) generated by your system. If you send the same key in a subsequent request, Travomatrix will recognize it and return the original response without executing the business logic (or wallet debit) again.

### Example Workflow

1. **Generate Key:** Your system generates `Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000`.
2. **Send Request:** You call `POST /booking/create`.
3. **Timeout:** Your connection drops before you receive a response.
4. **Retry:** You send the exact same request with the **same** `Idempotency-Key`.
5. **Safe Response:** Travomatrix sees the key, finds the existing (or currently processing) booking, and returns the successful PNR. **No second debit occurs.**

```bash theme={null}
curl -X POST https://api.travomatrix.com/api/v1/booking/create \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{...}'
```

## Retry Strategy

For non-idempotent endpoints (like Search), use a standard exponential backoff strategy. For idempotent endpoints:

| Status Code     | Action                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------- |
| `2xx`           | Success. No retry needed.                                                                   |
| `4xx`           | Client error (Validation, Insufficient Funds). **Do not retry** without fixing the payload. |
| `409`           | Conflict. The same idempotency key is being used for a different payload.                   |
| `5xx` / Timeout | **Retry** with the same `Idempotency-Key`.                                                  |

## Best Practices

* **Persistence:** Store your idempotency keys in your database alongside your local order record.
* **Uniqueness:** Never reuse an idempotency key for a different passenger set or different flight.
* **Expiration:** Idempotency keys are typically cached for 24 hours.