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

# Conventions

> Transport, naming, dates, money, headers and the error envelope.

## Transport and encoding

* HTTPS only. Requests are `POST` with `Content-Type: application/json`, except order status, which is a `GET` with no body. Every response is JSON.
* Property names are **camelCase**, including dictionary keys (baggage per passenger type is keyed `adult`, `child`, `infant`).
* **Enumerations are strings** in responses (`"tripType": "RoundTrip"`). Requests accept the name (`"Economy"`) or the number (`1`). See [Enumerations](https://developers.ttool.travel/reference/enumerations.md).
* Search and offer ids are GUIDs. Order ids are integers.
* Offers carry IATA codes for airlines and airports. Their English names come once per response in the [`dictionaries`](https://developers.ttool.travel/reference/offer-object#dictionaries) block.
* Optional fields with no value are omitted from the JSON rather than sent as `null`.
* Money is decimal, in the offer's `price.currency`.

## Dates and times

| Kind | Format | Example |
| - | - | - |
| Flight times | Local airport time, no offset | `2026-12-07T03:00:00` |
| Date-only fields | `yyyy-MM-dd` | `2026-12-07` |
| Durations | Integer minutes | `150` |

## Headers

| Header | Direction | Required | Description |
| - | - | - | - |
| `Authorization: Bearer {token}` | Request | Yes, except authenticate | Token from [authenticate](https://developers.ttool.travel/api-reference/authenticate.md) |
| `Content-Type: application/json` | Request | Yes | |
| `X-Correlation-Id` | Both | Recommended | Your request id: letters, digits, `. _ : -`, up to 64 characters. Echoed back, generated when absent. Quote it in support requests. |
| `X-Api-Version` | Request | No | Alternative to the `/v1/` path segment |

## Responses

A successful call (HTTP 200) returns the resource **directly**, with no wrapper. A failed call (4xx or 5xx) returns the error envelope:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": {
    "errorCode": "FLIGHT_PRICE_CHANGED",
    "errorMessage": "Flight price has changed. Please search again and review the new price before booking.",
    "errorCategory": "Conflict",
    "httpStatusCode": 409,
    "correlationId": "7b1c8f1e-4d2a-4f3e-9a7b-1c2d3e4f5a6b",
    "timestamp": "2026-10-25T07:22:46.158Z",
    "errorDetails": { "oldTotalPrice": 412.50, "newTotalPrice": 436.00 },
    "validationErrors": [],
    "suggestedAction": "Search again and book the refreshed offer.",
    "documentationUrl": null
  },
  "correlationId": "7b1c8f1e-4d2a-4f3e-9a7b-1c2d3e4f5a6b",
  "timestamp": "2026-10-25T07:22:46.158Z"
}
```

**error.errorCode** `string`

Stable machine-readable code. Branch on this, never on the message. Full list in [Errors](https://developers.ttool.travel/reference/errors.md).

**error.errorMessage** `string`

English text for humans. It may change, so don't parse it.

**error.errorCategory** `string`

One of `Validation`, `Authentication`, `NotFound`, `Conflict`, `Payment`, `Provider`, `Timeout`, `RateLimit`, `System`, `BusinessRule`.

**error.httpStatusCode** `integer`

Same as the HTTP status.

**error.errorDetails** `object`

Optional context. For validation failures it maps field names to lists of messages.

**error.suggestedAction** `string`

What to do next.

**correlationId** `string`

Trace id for support.

### Validation failures

HTTP 400 always uses `INVALID_REQUEST_FORMAT` and names each offending field:

```json theme={null}
"errorDetails": {
  "segments": ["RoundTrip searches take exactly two segments: the outbound and the return."],
  "flightPassengers[0].passportNumber": ["PassportNumber is required for passport travellers."]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.