Skip to main content
Every Jinko endpoint returns errors as JSON in a consistent envelope: 
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "departure_date must be in the future",
    "details": { "field": "departure_date" }
  }
}
The SDK converts these to ApiError (or its subclasses AuthError / ValidationError), see SDK error handling.

​
Status code reference

StatusWhenCommon causesWhat to do
400 Bad RequestRequest shape / values rejected before any business logicMissing required field, wrong type, malformed JSONInspect error.message; for the SDK, also catch ValidationError
401 UnauthorizedAuth header missing, malformed, or revokedForgot Authorization / X-API-Key header; key rotated; OAuth token expired and refresh failedVerify credentials. If you’re on MCP and pasting a CLI OAuth token, see OAuth, wrong issuer
403 ForbiddenAuthenticated but not allowedEndpoint requires a higher tier; account inactiveCheck the dashboard for account status; reach out if surprised
404 Not FoundResource doesn’t exist OR (on guest endpoints) credentials don’t matchtrip_id typo; booking_ref + last_name pair doesn’t resolveVerify the ID. On get_booking and refund/exchange guest paths, “not found” is intentionally indistinguishable from “wrong last_name”, don’t leak existence
409 ConflictState doesn’t allow the operationTrying to add an item to a fulfilled trip; double-checkout on a quoted tripRe-fetch state with getTrip before retrying
422 Unprocessable EntityValidated and authorized, but the upstream rejectedProvider says no inventory; price changed beyond toleranceRe-run discovery / live pricing; the offer is stale
429 Too Many RequestsRate limitFree tier is 1,000 requests / 30 days per API keyWait, or email dev@gojinko.com for a quota bump
500 Internal Server ErrorWe blew upBug, missing env var, a downstream provider’s outage we didn’t degrade gracefullyCapture the X-Request-ID from your response headers and report, see below
502 / 503 / 504Upstream provider failureTravelFusion / Sabre / Nuitée timed out or returned a bad responseRetry once after a small delay; if it persists, the provider is down

​
Reporting issues

Every response includes an X-Request-ID header (also visible in SDK logs as X-Request-ID). Capture it and include in any bug report, we use it to find the exact request server-side in Datadog. 
curl -i ... | grep -i x-request-id

try {
  await client.findFlight(...)
} catch (err) {
  if (err instanceof ApiError) {
    console.error('Request ID:', err.requestId)  // include this when reporting
  }
}
Email: dev@gojinko.com.

​
Common gotchas

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

If the token came from jinko auth login, it’s a CLI OAuth token (issuer = Jinko Auth user pool). MCP expects either an API key or an MCP-OAuth JWT (issuer = AuthKit). They look similar but trip the issuer check. Use jnk_* for programmatic MCP access.

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

Confirmation emails go via Resend. If the user’s email is correct on the trip’s contact and the booking status is completed, check spam. If the status is stuck on fulfilling for more than ~6 hours, the upstream provider is slow, common on TravelFusion when the airline is laggy.

​
”trip_item_token rejected with ‘expired’”

trip_item_tokens have a TTL (~30 minutes for flights, shorter for some hotel rates). If the user takes a long time on traveler entry, re-run live pricing (flight_search / hotel_search) before adding to a trip.