Statuses and errors

A hotel AI search answer has two layers. The HTTP status says whether the request was accepted. When it was, the status field says where the search is. Check the HTTP status first, then status.

Task status

Every successful answer (200 or 202) carries status, on POST /v1/hotel_ai_search, on the task read and on :cancel.

`status`	Meaning	What to do
`working`	The search is running. A `202` always carries this status.	Read the task again after `Retry-After` seconds, or stream its events.
`input_required`	The reply asks the traveler a question; `question` says what is missing. The task waits for the answer.	Show `message`, then send the traveler’s answer with the same `context_id`. See Answer a question.
`completed`	The turn ended. `hotels` holds the results, or is empty when nothing matched.	Show `message` and the hotels.
`failed`	The turn could not finish; `error` says why.	See Why a search fails.
`canceled`	The task was canceled, or a later message replaced it; then `superseded_by` names the new task.	Read the task in `superseded_by`, if any.

On POST /v1/hotel_ai_search without streaming, a 200 always carries one of the last four statuses: the turn is over, and nothing more arrives for it. The task read answers 200 with any status, working included, so keep reading it while status is working. A completed reply can still ask the traveler something, with no question field, for example Tell me which condition to drop. when no hotel matches every filter, or Tell me where and when you'd like to stay, and I'll search hotels. for a message that is not a hotel request. Always show message. The traveler’s reply goes in the same conversation. In the event stream, task.status events also carry submitted, the moment a turn is accepted. A task read shows that moment as working.

Why a search fails

A failed task answers 200 with status: "failed" and an error:

{
  "context_id": "ctx_mvinvg98ecb918c84c4e6770",
  "task_id": "atk_mvinvg9d9c9e4c6732210eeb",
  "status": "failed",
  "error": { "code": "deadline_exceeded", "message": "The search took too long. Please send the message again." }
}

`error.code`	Cause	`error.message`	What to do
`understanding_failed`	The message could not be read as a hotel search.	`The message could not be understood. Please rephrase it.`	Ask the traveler to rephrase.
`unsupported_currency`	The search cannot price in the `currency` you sent.	`The search does not support this currency.`	Send another currency, such as `USD` or `EUR`.
`invalid_timezone`	The time zone is not a known IANA time zone. Normally rejected first with `422`.	`The time zone is not a known IANA time zone.`	Send an IANA name such as `Europe/Paris`.
`deadline_exceeded`	The turn did not end within 90 seconds.	`The search took too long. Please send the message again.`	Send the message again.
`search_refused`	The hotel search refused the request.	`The search could not be completed. Please try again.`	Send the message again; contact support if it repeats.
`agent_error`	An error stopped the turn.	`The search could not be completed. Please try again.`	Send the message again.
`max_attempts_exceeded`	The turn was stopped after repeated errors.	`The search could not be completed. Please try again.`	Send the message again.
`context_expired`	The task was waiting for an answer when its conversation expired (24 hours without a message).	`The search could not be completed. Please try again.`	Start a new conversation without `context_id`.

message is safe to show to the traveler. Branch on code.

HTTP statuses

Errors use the Jinko error format: {"error": {"code": "...", "message": "..."}}. See Errors.

All four routes

HTTP	`error.code`	When	What to do
`400`	`BAD_REQUEST`	Malformed JSON (`Malformed JSON in request body`), or an invalid header such as a reserved `X-End-User-Id`.	Fix the request.
`401`	`AUTH_REQUIRED`	No key (`Missing X-API-Key or Authorization header.`), a key that is not a `jnk_` key, or an invalid or expired key (`Invalid or expired API key.`).	Send a valid key; see API keys.
`403`	`FORBIDDEN`	The key is valid but may not run live searches, for example `This API key is not granted the "search_live" scope required by this endpoint`; or AI search is not enabled for the tenant: `Travel AI search is not enabled for this tenant.`	Check the key’s scopes in the dashboard. The key is valid, so do not rotate it.
`422`	`BAD_REQUEST`	A field or header is out of range; `message` names it, for example `timezone: Required`.	Fix the field.
`429`	`RATE_LIMITED`	The key has used up its request allowance (`The API key has used up its request allowance`).	Retry later; see Rate limits.
`502`	`UPSTREAM_ERROR`	The request could not be completed (`The request could not be completed.`).	Retry. On `POST`, retry with the same `Idempotency-Key`.
`503`	`TEMPORARILY_UNAVAILABLE`	The search is briefly unavailable.	Retry after a few seconds, with the same `Idempotency-Key` on `POST`.
`504`	`UPSTREAM_TIMEOUT`	No answer in time (`The request timed out before a result was available. Retry the request.`).	Retry with the same `Idempotency-Key`; the first message may already be running.

`POST /v1/hotel_ai_search`

HTTP	When
`200`	The turn ended within the wait: `completed`, `input_required`, `failed` or `canceled`. With `Accept: text/event-stream`, the turn as a stream. A retry with an `Idempotency-Key` whose turn is over also answers `200` with its stored answer.
`202`	The search is still running at the end of the wait: `status: "working"`, with `Location`, `Retry-After` and, when you sent `Prefer`, `Preference-Applied`.
`404`	`NOT_FOUND`, `No such conversation or task.`: the `context_id` is unknown or belongs to another key’s tenant, or the `task_id` is not in that conversation.
`410`	`GONE`, `This conversation has expired. Start a new one without context_id.`: no message for 24 hours.
`422`	The body is out of range. `text` must be 1 to 2000 characters; `timezone` is required and must be an IANA time zone; `currency` must be 3 letters (`currency: an ISO 4217 code`); `guest_nationality` must be 2 letters; `task_id` needs `context_id` (`task_id needs the context_id of its conversation`). Also `Idempotency-Key` outside 1 to 200 characters, and a body sent without a JSON `Content-Type`.

`GET /v1/hotel_ai_search/tasks/{task_id}`

HTTP	When
`200`	The task, with its current `status`.
`404`	`NOT_FOUND`, `No such task.`: the task is unknown or belongs to another tenant.
`422`	`task_id` is not 1 to 100 characters.

A task stays readable after its conversation expires.

`GET /v1/hotel_ai_search/tasks/{task_id}/events`

HTTP	When
`200`	The event stream.
`404`	`NOT_FOUND`, `No such task.`
`422`	`task_id` is not 1 to 100 characters, or `Last-Event-ID` is longer than 20 characters.

`POST /v1/hotel_ai_search/tasks/{task_id}:cancel`

HTTP	When
`200`	The task was `working` or `input_required` and is now `canceled`.
`404`	`NOT_FOUND`, `No such task.`
`409`	`CONFLICT`: the task has already ended, for example `The task has already ended (completed).`
`422`	`task_id` is not 1 to 100 characters.

Getting started

Guides

AI

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Task status

Why a search fails

HTTP statuses

All four routes

`POST /v1/hotel_ai_search`

`GET /v1/hotel_ai_search/tasks/{task_id}`

`GET /v1/hotel_ai_search/tasks/{task_id}/events`

`POST /v1/hotel_ai_search/tasks/{task_id}:cancel`

​Task status

​Why a search fails

​HTTP statuses

​All four routes

​POST /v1/hotel_ai_search

​GET /v1/hotel_ai_search/tasks/{task_id}

​GET /v1/hotel_ai_search/tasks/{task_id}/events

​POST /v1/hotel_ai_search/tasks/{task_id}:cancel

​Related

Task status

Why a search fails

HTTP statuses

All four routes

`POST /v1/hotel_ai_search`

`GET /v1/hotel_ai_search/tasks/{task_id}`

`GET /v1/hotel_ai_search/tasks/{task_id}/events`

`POST /v1/hotel_ai_search/tasks/{task_id}:cancel`

Related