Skip to main content
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.
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 CodeAction
2xxSuccess. No retry needed.
4xxClient error (Validation, Insufficient Funds). Do not retry without fixing the payload.
409Conflict. The same idempotency key is being used for a different payload.
5xx / TimeoutRetry 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.