Errors & troubleshooting

Request failures use the envelope below; branch on error.code. Typed payment submissions also return known payment outcomes, including declines, through PaymentAttemptOutcome; see Payment outcome codes.

{
  "error": {
    "code": "TRIP_EXPIRED",
    "message": "This trip lapsed on 2027-09-03T09:12:44Z and no longer accepts changes.",
    "doc_url": "https://docs.gojinko.com/concepts/errors"
  },
  "status": "expired"
}

The error object always carries code and message; doc_url is optional. Some codes include additional machine-readable data, at the locations listed in the reference table. Most extra keys sit at the top level, as siblings of error: above, status describes the state that refused the operation. HOTEL_NAME_LOW_CONFIDENCE and DESTINATION_LOW_CONFIDENCE carry their recovery data inside error, at error.top_candidates and, when available, error.suggested_retry. Read those nested fields to choose or confirm a candidate before retrying. Continue branching on error.code, and tolerate additional fields at either level.

error.code is a closed enum. The reference table below is the complete set of error.code values: the platform sends no error.code that is missing from it, and every code on it has a producer. It is published as the code enum on ErrorResponse in the OpenAPI document, and this page is kept in step with that enum. Some refusals also carry a sibling code beside error.code with a finer reason; those values are listed under Sibling codes.New codes are added in a minor version and never change meaning. See Versioning & deprecation for what that entitles you to.

The SDK converts every one of these to ApiError with statusCode, see SDK error handling.

Error code reference

Code	Status	Extra keys (location)	What it means, and what to do
`AUTH_REQUIRED`	401		The key is missing, malformed, expired, or not valid for this environment. Send a valid key in the header for the surface you are calling: `X-API-Key` on REST, `Authorization: Bearer` on MCP. See Which header to send. A sandbox key does not work against production.
`PAYMENT_REQUIRED`	402		Your organization’s balance cannot cover this call. Top up; retrying never fills an empty wallet, and the key itself is fine. Set up Auto top-up to replenish credit automatically.
`RATE_LIMITED`	429		A rate limit or quota was exceeded. Back off and retry the same request, honouring `Retry-After` when present. See Limits & credits.
`BAD_REQUEST`	400, 422		The request was malformed or failed validation. Fix it as `message` describes; retrying it unchanged cannot succeed.
`HOTEL_NAME_LOW_CONFIDENCE`	422	Inside `error`: `top_candidates`, `suggested_retry`	No exact hotel-name match and no clear best candidate. Read `error.top_candidates`; retry with a matching `hotel_id`, or ask the user to choose.
`DESTINATION_LOW_CONFIDENCE`	422	Inside `error`: `top_candidates`, `suggested_retry`	No exact catalog city and no clear best candidate. Confirm the city, then retry with `error.suggested_retry.destination` when available.
`FORBIDDEN`	403		The credential is valid, and this request is refused anyway: the key lacks the scope or role this route needs. Do not rotate the key, it is working. Check its scopes in the dashboard, and check you are calling the environment it belongs to.
`NOT_FOUND`	404		No resource with that identifier is visible to this caller. Check the identifier and use a credential authorized for the booking’s owner or tenant. On guest lookups, “not found” is deliberately indistinguishable from “wrong last name”. See booking lookup and hotel cancellation.
`CONFLICT`	409		The resource’s current state refuses the operation, for a reason with no more specific code. Re-read the resource and act on what it says, never retry blindly.
`GONE`	410		The resource this request names existed and no longer does. Re-acquire it — search again, or check out again to re-quote — then retry with the new identifier. Repeating this request with the same one cannot succeed.
`QUOTE_EXPIRED`	410	`expires_at`, `quote_id`, `reason`; on a typed payment also `payment_error`, `recovery`	The quote can no longer be paid: it passed its `expires_at`, or the trip’s travelers changed after it was priced (`reason: travelers_changed`). Payment was refused before any payment object was created. Call `POST /v1/checkout` again on the same trip, which re-quotes, then mint a new payment token against the new `agent_spt_params` and submit it against the new `quote_id`. Nothing was charged. Detail below.
`QUOTE_PENDING`	503	`retry_after_seconds`, `quote_id`	The trip’s quote is still being priced. Checkout waits about 55 seconds for it, then answers this instead of holding the request. Call `POST /v1/checkout` again after the interval in `Retry-After`: the call picks up the same quote and answers with the checkout once it is priced.
`TRIP_EXPIRED`	409	`status`	The trip lapsed (24 hours with no activity) and no longer accepts writes. Start a new trip and add the items again; a lapsed trip cannot be revived. Detail below.
`TRIP_STATE_CONFLICT`	409	`status`	The trip is in a state that refuses this operation: payment already started (`fulfilling`, `fulfilled`, `partially_fulfilled`), or it is `cancelled` or `failed`. Read `status` and act on it. Nothing was written. Detail below.
`OFFER_EXPIRED`	410		The search offer is no longer usable: its token expired, or the supplier rejected it as expired or missing during pricing. No payable quote was established. Search again, replace the unavailable item using the latest search result, and check out promptly. Show that the flight offer is no longer available; do not describe this as an established quote expiring (`QUOTE_EXPIRED`).
`OFFER_UNAVAILABLE`	409		The provider can no longer quote this offer. Emitted today when the hotel supplier has no rate for your occupancy at quote time. Search again for the occupancy you intend to book and pick a rate that covers it; this one cannot be quoted at any price.
`MISSING_CUSTOMER_DETAILS`	422	`missing_fields`, `missing_by_domain`	The trip has no travelers, or no contact carrying both an email and a phone, or a traveler lacks a passenger document the carrier requires (see `required_attributes` in Required traveler attributes). Send `upsert_travelers` with the travelers, a contact and the fields named in `missing_fields`, then check out again.
`INVALID_PHONE_NUMBER`	422		A phone number is not in international format: it has no leading `+` and country code, is not a possible number, or carries an extension. Nothing was written. Resend the number with a leading `+` and country code, for example `+12025550147`. Spaces, hyphens, dots and parentheses are accepted and removed.
`CURRENCY_UNSUPPORTED`	400		The requested currency is not supported for this operation. Agent SPT payment supports USD and EUR, whichever Stripe account the partner is bound to.
`INVALID_SEGMENTS_TO_EXCHANGE`	400		An exchange selection is malformed, or does not match a booked leg. For a leg the booking does not have, `message` lists the booked legs: name each leg to change by its first departure and final arrival airport, as `get_booking` lists it, not by a connection airport.
`PARTIAL_EXCHANGE_UNSUPPORTED`	400		The supplier cannot keep the unselected legs unchanged for this booking. Name every booked leg in `segments_to_exchange` to reshop the whole itinerary. When the supplier refused, `message` is fixed: “This exchange cannot be processed as requested. Change the selected flights or contact Jinko support.”
`LEG_ALREADY_DEPARTED`	400		A leg named in `segments_to_exchange` has already departed, and a departed leg cannot be changed. `message` lists the booked legs. Keep it out of `segments_to_exchange`; a departed leg that is not named stays as booked.
`DEPARTURE_DATE_IN_PAST`	400		A new departure date is before today at the leg’s departure airport. `message` lists the booked legs. Choose a date from today on.
`LEG_DATES_OUT_OF_ORDER`	400		The new dates would put the legs out of order: a changed leg would leave before the previous leg arrives, or after the next leg leaves. `message` lists the booked legs; change the dates, or change the other leg too.
`INVALID_EXCHANGE_REQUEST`	400		The supplier refused the exchange request itself. `message` is fixed: “This exchange cannot be processed as requested. Change the selected flights or contact Jinko support.” Change the selected flights, or contact Jinko support; repeating the request unchanged cannot succeed.
`NOT_EXCHANGEABLE`	409		The booking cannot be exchanged as it stands: no ticket or flight is left to change, or the fare does not permit the change. `message` is fixed: “This booking cannot be exchanged online. Contact Jinko support.” Retrying cannot succeed. On `exchange_shop` it is `error.code`; on `exchange_price` and `exchange_commit` the refusal is `error.code: "CONFLICT"` with the sibling `code: "not_exchangeable"`.
`CREDENTIAL_FORMAT_INVALID`	400	`payment_error`, `recovery`	The typed payment body or `Idempotency-Key` has an invalid format, or the key is missing. Correct the named field and resubmit with a valid `Idempotency-Key`.
`PAYMENT_TYPE_NOT_ENABLED`	403	`payment_error`, `recovery`	This payment type is not enabled for the caller. Choose a type listed in `accepted_payment_types`, or contact support.
`PAYMENT_CREDENTIAL_INVALID`	400	`payment_error`, `recovery`	The payment credential is invalid. Follow `recovery.action` and supply a replacement credential when it asks for one.
`TRIP_OWNED_BY_OTHER_PAYMENT`	409	`payment_error`, `recovery`	Another payment attempt owns this trip. Read the existing attempt and follow its recovery action before paying again.
`IDEMPOTENCY_KEY_REUSED`	409	`payment_error`, `recovery`	The `Idempotency-Key` was already used for a different submission. Resend the original request with this key, or use a new key for a new submission.
`ATTEMPT_IN_PROGRESS`	409	`payment_error`, `recovery`	A payment attempt is already in progress. Poll it and follow `recovery.action`.
`ATTEMPT_TERMINAL`	409	`payment_error`, `recovery`	This payment attempt has reached a terminal state. Read its outcome and follow `recovery.action` before starting another attempt.
`TEMPORARILY_UNAVAILABLE`	503	`payment_error`, `recovery`	Payment submission is temporarily unavailable. Wait for `Retry-After` when present and follow `recovery.action`.
`UPSTREAM_REJECTED`	502		A travel supplier read the request and declined it. Try another offer, or change the request; repeating it unchanged cannot succeed.
`UPSTREAM_UNAVAILABLE`	503		No supplier can serve the request right now, for a reason that is not your request. Retry unchanged after the interval in `Retry-After`.
`UPSTREAM_TIMEOUT`	504		A travel provider, or the platform behind this API, did not answer in time; the API stops waiting after 58 seconds rather than hold the request. Retry a read unchanged. Before repeating a request that changes something, read the resource’s state: the operation may still have completed.
`UPSTREAM_ERROR`	502		An upstream call failed for a technical reason, with no verdict that the request itself was invalid: a technical pricing failure, an unreadable body, or a status we do not map. Retry once. If checkout pricing still fails, choose another flight or contact support; for any other repeated failure, contact support.
`INTERNAL`	500		The platform failed. Retry; if it persists, report it with the request id.

Retryable and non-retryable failures share status codes, so branch on the code. A 409 OFFER_UNAVAILABLE requires a different offer, while a 409 TRIP_STATE_CONFLICT means payment already started on the trip, or it was cancelled or failed. Handle each cause before retrying.

An SPT currency refusal (CURRENCY_UNSUPPORTED) means the trip is quoted in a currency other than USD or EUR. Pay through hosted checkout with the checkout_url from your earlier checkout response, or search again in USD or EUR.

Messages on supplier failures

These codes always carry the same message, and it never includes text from a supplier; details carries none either. A 503 stays 503 UPSTREAM_UNAVAILABLE (with Retry-After) and a 504 stays 504 UPSTREAM_TIMEOUT; neither is folded into a 502. Branch on error.code, not on the message.

Code	Status	`error.message`
`UPSTREAM_REJECTED`	502	The request was declined for this offer. Try another offer.
`UPSTREAM_UNAVAILABLE`	503	The service is temporarily unavailable. Retry after the Retry-After delay.
`UPSTREAM_TIMEOUT`	504	The request timed out before a result was available. Retry the request.
`UPSTREAM_ERROR`	502	The request could not be completed.
`RATE_LIMITED`	429	Too many requests. Retry after the Retry-After delay.
`OFFER_UNAVAILABLE`	409	This offer is no longer available. Search again.
`OFFER_EXPIRED`	410	This offer has expired. Search again.

A supplier’s refusal of a request that Jinko itself accepted keeps its status and code, with a fixed message instead of the supplier’s words:

When	Status	`message`
A supplier refused the request’s inputs (search, pricing, booking, hotel search)	400	The request was declined for these inputs. Check the dates, places and travellers, then retry.
A car rental operation was refused	422	The rental request was declined. Try another vehicle, location or time.
`INVALID_EXCHANGE_REQUEST`, or `PARTIAL_EXCHANGE_UNSUPPORTED` when the supplier refused	400	This exchange cannot be processed as requested. Change the selected flights or contact Jinko support.
`NOT_EXCHANGEABLE`, or the sibling `code: "not_exchangeable"`	409	This booking cannot be exchanged online. Contact Jinko support.
`not_cancellable` (the sibling `code` on a refund or cancellation refusal)	409	This booking cannot be cancelled online. Contact Jinko support.
A successful servicing answer whose reason field would otherwise hold the supplier’s words, such as `manual_reason`	200	This request needs manual handling by Jinko support.

A message Jinko writes from its own checks, such as a missing field or a leg selection that does not match the booking, keeps its own text.

Payment outcome codes

Typed payment submissions report payment outcomes in payment_error.code (or null when there is no payment error), with exactly one recovery.action. These codes are uppercase and share their names with error.code: a refusal before the attempt is accepted carries the same code in both. A 200 can contain a decline; a 202 means pending. Follow the returned recovery action, not the HTTP status alone. The legacy flat SPT body does not use them.

CREDENTIAL_FORMAT_INVALID: 400; fix the request and replay the same key if that key was valid (a rejected Idempotency-Key needs a valid key instead).
PAYMENT_TYPE_NOT_ENABLED: 403; stop.
PAYMENT_CREDENTIAL_INVALID: credential unusable; correct before acceptance, replacement + new key after cleanup.
TRIP_OWNED_BY_OTHER_PAYMENT: 409; stop.
IDEMPOTENCY_KEY_REUSED: 409; stop, read the original attempt.
ATTEMPT_IN_PROGRESS: poll; competing attempts get 409.
CARD_DECLINED: the card was declined; follow recovery.action.
PAYMENT_CREDENTIAL_REJECTED: SPT rejection; replacement + new key on a valid quote once quiescent.
AUTHENTICATION_REQUIRED: follow the returned recovery.action; replace the credential once allowed.
AUTHENTICATION_FAILED: poll cleanup, then replacement or recheckout.
AUTHENTICATION_ABANDONED: poll, then recheckout.
QUOTE_EXPIRED: 410 before acceptance; recheckout.
ATTEMPT_TERMINAL: 409 before acceptance (recovery.action: stop). After acceptance it arrives in the normal payment outcome: follow recovery.action (poll during cleanup, then retry_new_key on a valid quote or recheckout if it expired).
PAYMENT_OUTCOME_UNKNOWN: poll until recovery.action changes; a new key only when it returns retry_new_key, or recheckout if the quote expired.
FULFILLMENT_DISPATCH_DELAYED: poll; no second payment.
RECONCILIATION_REQUIRED: contact support.
TEMPORARILY_UNAVAILABLE: 503 before acceptance: retry same key; after: poll.

Sibling codes

A few refusals answer with a general error.code and put the finer reason in a sibling code field beside error. Branch on error.code first, then on code:

Where	`error.code`	Sibling `code` values
Refund and cancellation preview or commit (flight, hotel, rental car)	`CONFLICT`	`quote_drift`, `QUOTE_EXPIRED`, `active_operation_exists`, `not_cancellable`, `funds_unavailable`; flight and hotel also `superseded`; flight and rental car also `manual_required`; flight also `penalty_exceeds_sell`, `multi_currency_basis`
`exchange_price`, `exchange_commit`	`CONFLICT`	`not_exchangeable`, `funds_unavailable`, `multi_currency_basis`, `manual_required`; `exchange_commit` also `exchange_in_progress`
Webhook delivery replay	`CONFLICT`	`delivery_in_progress`, `payload_purged`

Sibling codes keep the spelling shown here, mostly lowercase; only QUOTE_EXPIRED is uppercase, because it is also an error.code. Compare them exactly as listed. On a quote_drift refusal whose quote is still valid, retry_quote_id names the quote to commit again.

Booking lookup and hotel cancellation

Get Booking and Hotel Cancel support two ways to identify a booking:

Guest verification: provide booking_ref and last_name together.
Authenticated owner: provide booking_ref with a credential authorized for that booking. last_name is optional in this mode; omitting it does not bypass the ownership check. A tenant key needs the post_booking scope and access to the booking’s tenant.

For hotel cancellation, select the item’s booked_item_id from get_booking and use it throughout preview, commit and status. It may be omitted only when the booking has exactly one hotel item. The public REST API distinguishes invalid input from a booking the caller cannot access:

Request	Result
`last_name` without a booking reference or another supported identifier	`BAD_REQUEST` (400 or 422): the request is incomplete.
Well-formed `booking_ref` without `last_name`, with an authorized credential, but no matching accessible booking	`NOT_FOUND` (404): reference-only lookup is valid authenticated input.
`booking_ref` and `last_name`, but the reference does not exist or the name does not match	`NOT_FOUND` (404): both cases deliberately have the same refusal.

The authenticated not-found rule also applies to hotel cancellation preview and the legacy one-shot cancellation. A refused preview returns no quote handle. Builder MCP reports an unknown or inaccessible booking as structuredContent.status: "not_found"; its error envelope differs from the REST envelope above. Do not retry a 404 with guessed surnames or identifiers. Confirm the booking reference and the caller’s access. Do not treat a missing last_name alone as a validation failure for an authenticated owner.

Duplicate operations are not an error

Trip edits and checkout handle repeats as follows:

Creating a trip is never idempotent. Two calls to POST /v1/trip with no trip_id make two trips. That is the contract, not a race you lost. Hold the trip_id from the first response.
add_item and upsert_travelers are idempotent by identity. Adding the same offer twice leaves one item; upserting travelers twice leaves one set. You get a 200 and the current state, not a conflict.
Calling checkout twice is not an error either. A repeat call on the same trip returns 200 with the same session_id and checkout_url while the quote is still valid.

For trip creation, read the trip you already have before retrying. For typed payment submission, the first accepted request wins: replay it with the same idempotency key. Changing a compared safe field (trip, quote, payment type, amount, currency) with the same key returns 409 IDEMPOTENCY_KEY_REUSED; changing only the payment credential replays the first accepted attempt (send a new key for a new credential). Follow the payment outcome recovery action before attempting another payment.

The price moved: what happens

This is the single most commonly misunderstood behaviour in the API, so read it before you write your checkout path. By default, checkout proceeds at the new price. It does not fail, and there is no tolerance threshold. Live pricing is a moment in time, and by the time the customer reaches checkout the airline or hotel may quote something different. Jinko takes the provider’s current price and tells you it changed. Two fields on the affected items[] entry carry the signal:

Field	Meaning
`price_changed`	`true` when this item’s price moved since it was quoted. Absent otherwise.
`original_price_money`	What it used to cost. `price_money` holds the new, live figure.

{
  "item_id": "prod_f5pyznimu4",
  "kind": "flight",
  "price_money":          { "value": 21420, "currency": "USD", "decimal_places": 2, "display": "USD 214.20" },
  "original_price_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" },
  "price_changed": true,
  "price_change": {
    "original_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" },
    "current_money":  { "value": 21420, "currency": "USD", "decimal_places": 2, "display": "USD 214.20" },
    "delta_money":    { "value": 2555,  "currency": "USD", "decimal_places": 2, "display": "USD 25.55" }
  }
}

Check price_changed on every checkout response. If you ignore it, you will charge a customer a price they never agreed to. Checkout returns the current price with price_changed: true and price_change (original_money, current_money, and delta_money, whose value is signed) on each affected item. The deprecated price, original_price and price_change.original / .current / .delta carry the same figures in major units. Ask the customer to accept the updated price before taking payment. The former fail_on_price_change option is no longer supported.

When a search offer cannot be priced

POST /v1/trip creates or edits the trip; it does not start pricing. POST /v1/checkout (/v1/book is deprecated) starts pricing and waits for success or failure. A supplier can reject the offer during this step even when Jinko still holds its token. That returns 410 OFFER_EXPIRED before any valid quote exists. Display “This flight offer is no longer available; please search again.” GET /v1/trip/{id} can then show quote.status: "failed". A failed quote has no payable price, even if an older response also carries expires_at. The quote can include failure_reason ("offer_expired" or "offer_unavailable") and a safe failure_message; expires_at is absent on failed quotes. Polling the trip does not start or retry pricing. Search again, replace the unavailable item from the latest result, and call checkout. Complete checkout promptly and search again after a delay. Suppliers can withdraw offers before Jinko’s token retention ends; there is no universal safe maximum offer age. See offer freshness for the optional freshness timestamps and how to handle missing values.

After a quote expires

Read the actual payment deadline from quote.expires_at on a successfully priced get_trip response or expires_at on checkout. Do not calculate it from a fixed duration. Past that instant the price is stale, and the platform will not spend your customer’s money on it.

A payment attempted after expires_at is refused, not re-priced. POST /v1/agent_payment/submit answers 410 QUOTE_EXPIRED and creates no payment object, so nothing is authorized, nothing is captured, and the trip and its quote are left exactly as they were.

{
  "error": {
    "code": "QUOTE_EXPIRED",
    "message": "The quote behind this checkout expired at 2027-09-04T12:39:56Z.",
    "doc_url": "https://docs.gojinko.com/concepts/errors"
  },
  "expires_at": "2027-09-04T12:39:56Z",
  "quote_id": "2097152"
}

The remedy is two calls. Call POST /v1/checkout again on the same trip: an expired quote is never reused, so this re-quotes and returns a fresh expires_at, a fresh total, and fresh agent_spt_params. Then mint a new payment token against those new params and submit it. Check price_changed on the new response before you do, because a re-quote is exactly when a price moves. Two clocks are in play here, and they are not the same clock:

Clock	Lifetime	What runs out
`expires_at` on the checkout response	Use the returned deadline	The quoted price. The same instant as `quote.expires_at` on `get_trip`.
The `checkout_url` signed token	4 hours	The link. After that the page does not open at all.

For hosted payment, call checkout again and send the customer the fresh link and updated price. The hosted page cannot re-quote on its own. The link lifetime is not a field you can read, and an openable link does not make an expired quote payable. Offers and trips expire on their own clocks. Lifetimes and expiry lists every lifetime in one table.

Fulfillment has its own terminal state for this, expired_quote, which means the quote ran out after the customer paid but before the booking was placed. That is a different moment from the 410 above, which happens before any money moves. See the flight booking guide for the full fulfillment table.

A trip that refuses to change

A trip accepts writes while it is draft. In any other state, add_item, remove_item and upsert_travelers are refused before anything is written, and so is POST /v1/checkout. Two codes tell you which kind of refusal you hit, and both carry the trip’s status beside the envelope:

TRIP_EXPIRED means the trip lapsed after 24 hours with no activity. status is expired. It is not recoverable: build a new trip from fresh offers.
TRIP_STATE_CONFLICT means the trip is past the point of change. status names which: fulfilling, fulfilled or partially_fulfilled because payment already started, or cancelled / failed.

{
  "error": {
    "code": "TRIP_STATE_CONFLICT",
    "message": "This trip is fulfilled and no longer accepts changes.",
    "doc_url": "https://docs.gojinko.com/concepts/errors"
  },
  "status": "fulfilled"
}

The distinction matters because the remedies differ. “You already paid for this” is something you reconcile by reading the trip and finding the booking; a lapsed, cancelled or failed trip means starting a new one.

Lapsing is lazy: a read applies it, a write does not. The 24 hours elapsing changes nothing on its own. The lapse is applied on the next read of the trip, and GET /v1/trip/{id} returns expired on that same call rather than one call later.Until that read happens the trip still sits at its old status, so a write to a trip nobody has read since it lapsed may still succeed. If you are resuming a trip you have not touched in a while, call GET /v1/trip/{id} first and reconcile on what it tells you, rather than relying on the next write to refuse you.

A search with no matches is not an error

A live POST /v1/flight_search in search mode where no offer matches the filters returns HTTP 200 with an empty offers list. It is a success: there is no error envelope. The body carries result: "no_matches" and an instruction to relay. When the request sent a filter that narrows the results, the instruction asks the user which filter to relax; otherwise it asks whether to try other dates or airports.

{
  "offers": [],
  "result": "no_matches",
  "instruction": "Search completed successfully, but no offers satisfied every filter sent: the filter combination is too restrictive for this route and dates. Ask the user which filter to relax before searching again."
}

That instruction is the one sent when the request carried a filter that narrows the results. Every such filter is applied exactly as sent, so no_matches then means the filter combination was too restrictive for this route and dates. When the request carried no narrowing filter, instruction reads “Search completed successfully, but no flights were found for this route and dates. Ask the user whether to try other dates or airports before searching again.” Both outcomes are also sent in the X-Jinko-Result and X-Jinko-Instruction response headers. They are deprecated: read the body. See Filters are always applied. A search answers no_matches whenever at least one airline source answered, even if another could not be searched. When some sources fail and others return offers, the response is a normal 200 with those offers; it does not say which sources failed. Only a search that could not be completed at all is an error, never an empty list: UPSTREAM_REJECTED, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE or UPSTREAM_TIMEOUT, with the fixed message listed under Messages on supplier failures. Follow the remedy for that code; retry a 503 or 504 later with the same filters. These outcomes apply to live search mode only. The CLI exits with code 0 for no_matches, and MCP returns its status: "empty", reason: "no_matches" envelope. See flight_search.

Status code reference

Statuses are a coarser signal than codes, but this is the shape of the space:

Status	When	What to do
400	Request shape or values rejected before any business logic	Read `error.message` and fix the request
401	Auth header missing, malformed, or revoked	Verify credentials. If you are on MCP with a CLI OAuth token, see OAuth
402	Your organization is out of credit	Top up. Do not retry, and do not rotate the key
403	Authenticated but not allowed (`FORBIDDEN`)	Check the key’s scopes in the dashboard. Do not rotate it, the credential is fine
404	Resource does not exist, or credentials do not match it	Verify the identifier
409	State refuses the operation	Branch on `error.code`: several codes in the table above use this status and require different remedies; for typed payments, follow the payment outcome and recovery action
410	The thing you named is gone: an expired quote or a stale offer	Re-quote or re-search, then retry with what you get back
422	The request contradicts itself, or a precondition is unmet	Read `error.message`, it names the offending field
429	Rate limit	Back off, honour `Retry-After`. Email dev@gojinko.com to raise the ceiling
500	The platform failed	Record the error and any available request ID, then report it
502	A supplier declined the request (`UPSTREAM_REJECTED`) or an upstream call failed (`UPSTREAM_ERROR`)	Try another offer after a rejection; retry once after an upstream error
503	No supplier can serve the request right now (`UPSTREAM_UNAVAILABLE`), or the quote is still being priced (`QUOTE_PENDING`)	Retry after the `Retry-After` delay
504	A supplier or the platform did not answer in time (`UPSTREAM_TIMEOUT`)	Retry a read; before repeating a write, read the resource’s state

Reporting issues

Responses do not always include X-Request-ID. Keep the request ID your client sends, and capture a response request ID when present. Include it, the UTC time, endpoint, HTTP status, and error code in a bug report.

curl -i ... | grep -i x-request-id

import { ApiError } from '@gojinko/api-client'

try {
  await client.flightCalendar({
    origins: ['JFK'], destinations: ['CDG'],
    trip_type: 'oneway', departure_dates: ['2027-06-15'],
  })
} catch (err) {
  if (err instanceof ApiError) {
    console.error({ code: err.code, statusCode: err.statusCode,
      docUrl: err.docUrl, details: err.details })
  }
}

Email: dev@gojinko.com.

Common gotchas

”All my prices are 100x too high”

A $159.77 fare rendering as $15,977. Money fields carry value in minor units: { "value": 15977, "currency": "USD", "decimal_places": 2, "display": "USD 159.77" }. Divide by 10 ** decimal_places before displaying, or show display. If you still read the deprecated trip and checkout total_amount ({ amount, currency }), that one is in major units; do not divide it. See Money & prices. The mirror symptom, prices 100x too small, is usually a hardcoded / 100 applied to a zero-decimal currency such as JPY or KRW.

”My key says Active in the dashboard but every call is failing”

If the calls come back 402 PAYMENT_REQUIRED, the key is fine and the organization is out of credit. Key status and credit are independent: a key stays active while its organization’s balance is empty, because nothing is wrong with the credential. Top up and the same key resumes immediately. Do not rotate it, and do not retry the 402 in a loop; no number of retries adds credit. See Limits & credits.

”I get 401 on the MCP endpoint with a token that worked yesterday”

If you are using a token saved by the retired CLI OAuth flow, it may fail the MCP issuer check. MCP expects an API key or a token from its own OAuth flow. The CLI now uses API keys: run jinko auth login --key jnk_t_..., or set JINKO_API_KEY.

”Trip says ‘fulfilled’ but I never got a confirmation”

If the user’s email is correct on the trip’s contact and booking_state is completed, check spam. If booking_state remains processing, the provider has not finished confirming the booking; contact support if it persists. Note that fulfilling is a value of the trip’s top-level status, not of fulfillment.status. The fields have different vocabularies; read booking_state for the booking’s progress. Trip status and booking state explains how they relate. See the flight booking guide for the full fulfillment table.

”My offer token is rejected as expired”

Offer availability has no universal safe maximum age. A supplier can withdraw an offer before its token expires; an unavailable offer can produce 410 OFFER_EXPIRED when priced. If the user takes a long time on traveler entry, re-run live pricing (flight_search / hotel_search) before adding to a trip.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Error code reference

Messages on supplier failures

Payment outcome codes

Sibling codes

Booking lookup and hotel cancellation

Duplicate operations are not an error

The price moved: what happens

When a search offer cannot be priced

After a quote expires

A trip that refuses to change

A search with no matches is not an error

Status code reference

Reporting issues

Common gotchas

”All my prices are 100x too high”

”My key says Active in the dashboard but every call is failing”

”I get 401 on the MCP endpoint with a token that worked yesterday”

”Trip says ‘fulfilled’ but I never got a confirmation”

”My offer token is rejected as expired”

​Error code reference

​Messages on supplier failures

​Payment outcome codes

​Sibling codes

​Booking lookup and hotel cancellation

​Duplicate operations are not an error

​The price moved: what happens

​When a search offer cannot be priced

​After a quote expires

​A trip that refuses to change

​A search with no matches is not an error

​Status code reference

​Reporting issues

​Common gotchas

​”All my prices are 100x too high”

​”My key says Active in the dashboard but every call is failing”

​”I get 401 on the MCP endpoint with a token that worked yesterday”

​”Trip says ‘fulfilled’ but I never got a confirmation”

​”My offer token is rejected as expired”

Error code reference

Messages on supplier failures

Payment outcome codes

Sibling codes

Booking lookup and hotel cancellation

Duplicate operations are not an error

The price moved: what happens

When a search offer cannot be priced

After a quote expires

A trip that refuses to change

A search with no matches is not an error

Status code reference

Reporting issues

Common gotchas

”All my prices are 100x too high”

”My key says Active in the dashboard but every call is failing”

”I get 401 on the MCP endpoint with a token that worked yesterday”

”Trip says ‘fulfilled’ but I never got a confirmation”

”My offer token is rejected as expired”