Tirth API · Guide
Rate limits
Limits per key and endpoint group, and the RateLimit headers.
Limits are counted per key, never per address, in groups of endpoints. Each of your two active keys has its own allowance.
The live limits
| Group | Per minute | Daily |
|---|---|---|
| Catalogue and content | 120 | 500 catalogue calls |
| Availability | 60 | None |
| Quotes | 30 | 2,000, plus 50 for each booking in the last 30 days |
| Booking writes | 20 | None |
| Booking reads | 120 | None |
| Overall | 300 | None |
- Every call counts toward Overall as well as its own group. Credit, invoices, webhooks, cases and privacy requests count toward Overall only.
- The sandbox halves every figure.
- A day is a day in India, from midnight IST.
- Tirth may set other limits for your company; your answers' headers always show the ones that apply.
The reference names each operation's group.
The headers
Every answer carries the limit of its tightest window:
| Header | What it holds |
|---|---|
RateLimit-Limit | The calls allowed in the window |
RateLimit-Remaining | The calls left in it |
RateLimit-Reset | Seconds until the window starts again |
Over a limit, the answer is 429 rate_limited with Retry-After, in seconds: wait that long before the next call.
curl -i "https://sandbox.api.tirth.com/v2/pujas?limit=1" \
-H "Authorization: Bearer $TIRTH_API_KEY"HTTP/2 200
ratelimit-limit: 60
ratelimit-remaining: 59
ratelimit-reset: 42Two more guards
- Quote sweeps. More than 30 different date or group-size quotes for one product in an hour stop quotes on that product for that key for an hour:
429 quotes_blocked, withRetry-After. - Seat holds. If fewer than 1 in 5 of your seat holds became bookings over 24 hours, holds are switched off for your company until Tirth reviews them:
409 holds_disabled.
Staying inside them
- Keep the catalogue in your own store and refresh it with
updated_sinceandIf-None-Match. An unchanged list or product answers304with its ETag, and you keep what you have. - Follow availability with
GET /v2/availability/changesrather than reading every product again. - Follow bookings with webhooks and the change feed rather than reading each booking on a timer.
const etags = new Map();
async function readPujas() {
const url = 'https://sandbox.api.tirth.com/v2/pujas?limit=50';
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${process.env.TIRTH_API_KEY}`,
...(etags.has(url) ? { 'If-None-Match': etags.get(url) } : {}),
},
});
if (response.status === 304) return null; // Nothing changed.
etags.set(url, response.headers.get('ETag'));
return response.json();
}