Reference

Errors & limits

The CLI and MCP tools share the same errors and limits.

Error format

Every error has error, a sentence you can show the user. Failures you can act on also carry a reason. The CLI prints errors to stderr:

{
  "error": "Too many rate requests",
  "exitCode": 4,
  "status": 429,
  "retryAfterSeconds": 42
}

MCP tools return isError: true with { status, error, reason, ... } as JSON text.

Reason	Meaning
`already_booked`	409. The stay already has a paid or finished order. Includes `agentOrderId`, `orderUrl` and, when there is a payment session, `statusUrl`.
`price_or_terms_changed`	409. The price went up or the terms changed when the booking was checked again. Includes `changes`. Get rates again.
`rate_unavailable`	422. The rate expired, sold out or could not be verified, or `roomId` or `ratePlanCode` is wrong. Get rates again and pick from the result.
`supplier_unavailable`	503 or 504. The hotel supplier could not be reached or timed out. Includes `retryable: true`; retry shortly.
`refused`	422. Any other refusal, e.g. invalid guests, too many attempts, or a search that matched more than 30,000 hotels (with `matched` and `maxMatches`).

Status	Meaning
`400`	Invalid input, an unknown argument, or something that looks like a payment card number. Includes `issues: [{ path, message }]`; stays over 15 nights are rejected here.
`401`	Not signed in, or the token was revoked or expired. CLI tokens expire after 90 days without use.
`404`	Hotel not found.
`409 / 422`	See the `reason`.
`429`	Rate limited. Wait `retryAfterSeconds` and retry.
`502`	The hotel supplier returned an unexpected error.
`503 / 504`	The supplier is unavailable (`reason: supplier_unavailable`), sign-in could not be checked right now, or a booking hit a brief failure. Includes `retryable: true`; retry in a few seconds.
`500`	Unexpected error.

Code	Meaning
`0`	Success.
`1`	Other error, including 404, 409, 422 and 5xx.
`2`	Invalid arguments, locally or HTTP 400.
`3`	Not signed in or token revoked (HTTP 401). stderr includes `loginUrl`.
`4`	Rate limited (HTTP 429). stderr includes `retryAfterSeconds`.

Per account, shared by the CLI, MCP tools and fortrip.ai.

Limit	Value
`Stay length`	1 to 15 nights. Check-in can't be in the past.
`Rooms`	Up to 8 per booking.
`Adults`	Up to 8 per room.
`Children`	Up to 8 per room, ages 0–17.
`Hotels per rates call`	Up to 15.
`Search results`	Up to 50 per page, 100 pages.
`Display currency`	CNY or USD. Bookings charge their own currency, usually USD.
`Guest names`	Latin letters as on the passport, e.g. Müller → Mueller.
`Card numbers`	Refused in contact details, guest names and special requests. The user pays only on the payment page.
`Payment link`	Valid for about 3 hours 45 minutes. Call booking again for a new one.
`Not supported`	Flights, activities, and changing or cancelling a booking. Email info@fortrip.ai with the order link.

Reference

The CLI and MCP tools share the same errors and limits.

Every error has error, a sentence you can show the user. Failures you can act on also carry a reason. The CLI prints errors to stderr:

{
  "error": "Too many rate requests",
  "exitCode": 4,
  "status": 429,
  "retryAfterSeconds": 42
}

MCP tools return isError: true with { status, error, reason, ... } as JSON text.

Reason	Meaning
`already_booked`	409. The stay already has a paid or finished order. Includes `agentOrderId`, `orderUrl` and, when there is a payment session, `statusUrl`.
`price_or_terms_changed`	409. The price went up or the terms changed when the booking was checked again. Includes `changes`. Get rates again.
`rate_unavailable`	422. The rate expired, sold out or could not be verified, or `roomId` or `ratePlanCode` is wrong. Get rates again and pick from the result.
`supplier_unavailable`	503 or 504. The hotel supplier could not be reached or timed out. Includes `retryable: true`; retry shortly.
`refused`	422. Any other refusal, e.g. invalid guests, too many attempts, or a search that matched more than 30,000 hotels (with `matched` and `maxMatches`).

Status	Meaning
`400`	Invalid input, an unknown argument, or something that looks like a payment card number. Includes `issues: [{ path, message }]`; stays over 15 nights are rejected here.
`401`	Not signed in, or the token was revoked or expired. CLI tokens expire after 90 days without use.
`404`	Hotel not found.
`409 / 422`	See the `reason`.
`429`	Rate limited. Wait `retryAfterSeconds` and retry.
`502`	The hotel supplier returned an unexpected error.
`503 / 504`	The supplier is unavailable (`reason: supplier_unavailable`), sign-in could not be checked right now, or a booking hit a brief failure. Includes `retryable: true`; retry in a few seconds.
`500`	Unexpected error.

Code	Meaning
`0`	Success.
`1`	Other error, including 404, 409, 422 and 5xx.
`2`	Invalid arguments, locally or HTTP 400.
`3`	Not signed in or token revoked (HTTP 401). stderr includes `loginUrl`.
`4`	Rate limited (HTTP 429). stderr includes `retryAfterSeconds`.

Per account, shared by the CLI, MCP tools and fortrip.ai.

Limit	Value
`Stay length`	1 to 15 nights. Check-in can't be in the past.
`Rooms`	Up to 8 per booking.
`Adults`	Up to 8 per room.
`Children`	Up to 8 per room, ages 0–17.
`Hotels per rates call`	Up to 15.
`Search results`	Up to 50 per page, 100 pages.
`Display currency`	CNY or USD. Bookings charge their own currency, usually USD.
`Guest names`	Latin letters as on the passport, e.g. Müller → Mueller.
`Card numbers`	Refused in contact details, guest names and special requests. The user pays only on the payment page.
`Payment link`	Valid for about 3 hours 45 minutes. Call booking again for a new one.
`Not supported`	Flights, activities, and changing or cancelling a booking. Email info@fortrip.ai with the order link.