Tirth API · Guide
Errors
The error envelope and every error code, with what it means.
Every error from the Tirth API has the same shape, so one piece of code can read them all. Branch on code, never on the words of message.
The envelope
{
"error": {
"code": "partner_reference_taken",
"message": "This partner_reference was used for another booking. Each one is used once.",
"field": "partner_reference",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}| Field | What it holds |
|---|---|
code | One of the codes below. Codes are only ever added, never renamed or removed. |
message | Plain English for a developer. It never repeats a value you sent. |
field | The part of the request at fault, such as partner_reference or Idempotency-Key, or null. |
request_id | The ID of this call, 32 hexadecimal characters. Quote it when you ask for help. |
A 429 and a 503 also carry a Retry-After header: wait that many seconds before trying again.
Another company's booking, refund or endpoint answers 404 not_found, exactly as one that does not exist, so nothing about it is revealed.
Codes for every call
| Code | Status | What it means |
|---|---|---|
validation_failed | 400 | The request is not valid: a field, a parameter or a header. field names it. |
unauthenticated | 401 | No key, a malformed or unknown key, a revoked or expired key, or a key for the other host. |
forbidden | 403 | The key lacks the scope, or the call came from outside its IP allowlist. |
not_found | 404 | Nothing here, or it belongs to another company. |
conflict | 409 | The request clashes with the current state, such as repeating a request whose secret was shown once. |
gone | 410 | It existed and has ended, such as a proof link past its 24 hours. |
precondition_failed | 412 | A condition you sent no longer holds. |
rate_limited | 429 | Too many calls for this key. Wait for Retry-After. |
internal | 500 | Something went wrong on Tirth's side. The message is generic; retry with the same Idempotency-Key. |
unavailable | 503 | The API cannot answer for now. Wait for Retry-After. |
Idempotency codes
| Code | Status | What it means |
|---|---|---|
idempotency_key_required | 400 | This write needs a UUID v4 in the Idempotency-Key header. |
idempotency_key_reused | 409 | The same key was used for a different request. |
idempotency_in_progress | 409 | The first request with this key is still being answered. Try again shortly. |
See Idempotency.
Quote and booking codes
| Code | Status | What it means |
|---|---|---|
quote_expired | 410 | The quote's price lock has ended, or a cancellation quote is past its time. Ask for a new one. |
quote_used | 409 | One quote makes one booking, and this one already did. |
credit_insufficient | 402 | Your credit does not cover the booking. Nothing is taken, and the quote's lock still stands. |
partner_reference_taken | 409 | You used this partner_reference before. It is unique for your company forever. |
hold_refused | 409 | A seat hold would go over a cap. Nothing is held: holds are never partial. |
holds_disabled | 409 | Seat holds are switched off for your company until Tirth reviews them. |
quotes_blocked | 429 | Too many different quotes for one product in an hour: quotes on it stop for this key for an hour. |
not_bookable | 409 | This product or option cannot be booked through the API. |
Change and cancellation codes
| Code | Status | What it means |
|---|---|---|
price_changed | 412 | The price of a change moved since its amendment quote. Ask for a new quote. |
not_amendable | 409 | This booking cannot be changed this way now. |
not_cancellable | 409 | Already cancelled, or not a booking that can be cancelled. |
cancellation_closed | 409 | A booking can be cancelled only before its scheduled start. |
Webhook and sandbox codes
| Code | Status | What it means |
|---|---|---|
endpoint_limit_reached | 409 | An environment has at most 3 active webhook endpoints. |
sandbox_only | 404 | This route is served only by the sandbox. |
not_advanceable | 409 | The sandbox booking has no next simulated stage: it is requested, at proof shared, or ended. |
Reading errors in Node
const response = await fetch(url, init);
if (!response.ok) {
const { error } = await response.json();
if (error.code === 'quote_expired') {
// Ask for a new quote and show its price again.
} else if (response.status === 429 || response.status === 503) {
const wait = Number(response.headers.get('Retry-After') ?? '1');
// Try again after `wait` seconds.
}
console.error(`${error.code} on ${error.field ?? 'the request'} (request ${error.request_id})`);
}