Concepts

Errors

One error shape for every failure, the HTTP codes we use, and the full catalogue of booking errors.

There are two kinds of errors:

  • Request errors are returned on the HTTP response when we cannot accept the request: bad input, missing scope, rate limits.
  • Booking errors happen later, while the order is being booked. They appear in the timeline and in order.failureCode once an order fails.

Error shape#

Every non-2xx response has the same body:

JSON
{
  "error": {
    "code": "INVALID_STATE",
    "message": "Order is issued; this action needs awaiting_price_confirmation",
    "requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c"
  }
}
  • code is stable. Match on it in your code.
  • message is for people and may change. Show it, log it, do not parse it.
  • requestId equals the x-request-id response header and finds the call in the request log.
  • issues is present only for VALIDATION_FAILED.

Request error codes#

HTTP code When What to do
400 VALIDATION_FAILED Body or query does not match the schema. Fix the fields listed in issues. Do not retry unchanged.
401 UNAUTHENTICATED No key or session, malformed, unknown, expired or revoked key. Check the key; create a new one if it expired or was revoked.
401 INVALID_CREDENTIALS Wrong e-mail or password at login. Ask the person to try again.
403 FORBIDDEN The key lacks a scope, the role is too low, or the route is dashboard-only. Use a key with the scope named in message.
403 ACCOUNT_SUSPENDED The account is suspended. Contact 1fly support.
403 LIVE_MODE_UNAVAILABLE A live key tried to create an order. Use a test key until live mode opens.
403 PLAN_LIMIT The plan does not include the feature, e.g. a live key on Free. Upgrade the plan.
404 NOT_FOUND, ORDER_NOT_FOUND No such resource in your account. Check the id and that you use the right account’s key.
409 INVALID_STATE The order’s status does not allow the action. Fetch the order and act on its current status.
409 WORKFLOW_NOT_RUNNING The order is no longer active. Treat the order as final.
409 EMAIL_TAKEN Signup with an e-mail that already has an account. Log in instead.
429 QUOTA_EXCEEDED The plan’s monthly order quota is used up. Do not retry; upgrade or wait for the next month.
429 RATE_LIMITED Too many requests this minute. Wait for Retry-After seconds, then retry.
500 INTERNAL Our bug. Retry with backoff; report the requestId if it persists.

New codes may be added in any minor release. Handle unknown codes by their HTTP status.

Validation issues#

VALIDATION_FAILED lists every problem at once, so you can fix them all in one go. path points into the request body (array indexes included):

JSON
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields are missing or invalid.",
    "requestId": "5b0c9a7e-2d1f-4e3a-9b8c-7d6e5f4a3b2c",
    "issues": [
      { "path": "passengers.0.lastName", "code": "invalid_format", "message": "Last name: use Latin letters A–Z exactly as in the passport (spaces, hyphens and apostrophes allowed, no accents or Cyrillic)." },
      { "path": "contact.phone", "code": "invalid_format", "message": "Use international format, e.g. +998901234567" }
    ]
  }
}

Show each message next to the field named by path. Messages are written for travellers.

Retrying#

Situation Retry?
Network error or timeout on POST /v1/orders Yes, with the same idempotencyKey.
429 RATE_LIMITED Yes, after Retry-After seconds.
500, 502, 503, 504 Yes, with exponential backoff (1 s, 2 s, 4 s …, at most 5 tries).
Any other 4xx No. Change the request first.

Booking error catalogue#

Generated from the engine’s error catalogue. Category says who must act (see Chronology). Retryable errors are retried automatically by 1fly; you never need to retry them yourself.

CodeCategoryRetryableWhat to do
PASSENGER_MIX_MISMATCHcustomerNoPassengers must match the search (adults, children, infants). Search again with the right mix.
NAME_NOT_LATINcustomerNoNames must use Latin letters exactly as in the passport.
PASSENGER_AGE_INVALIDcustomerNoAge does not match the passenger type on the date of the last flight.
INFANTS_EXCEED_ADULTScustomerNoEach infant must travel with its own adult.
PASSPORT_EXPIREDcustomerNoThe passport expires before the trip ends. Use a valid passport.
PRICE_CHANGEDsupplierNoThe airline changed the price. Ask the traveller to confirm the new price.
PRICE_REJECTEDcustomerNoThe traveller declined the new price.
PRICE_CONFIRMATION_TIMEOUTcustomerNoThe traveller did not answer the price change in time.
SOLD_OUTsupplierNoThis fare sold out. Offer the next cheapest flight.
SUPPLIER_TIMEOUTsupplierYesThe supplier did not answer in time; retried automatically.
SUPPLIER_REJECTEDsupplierNoThe supplier refused the request; its message says why. Search again or choose another flight.
PAYMENT_DECLINEDpaymentNoThe bank declined the card. The traveller can try another card or wallet.
PAYMENT_TIMEOUTcustomerNoNo payment arrived before the hold expired; the booking was cancelled.
ISSUE_REJECTEDsupplierNoThe airline refused to issue. The hold was released and the booking cancelled.
ISSUE_STATUS_UNKNOWNsupplierYesIssue timed out; checking status before trying again so no ticket is issued twice.
ISSUE_NOT_REQUESTEDcustomerNoPayment was held, but nobody asked to issue the ticket before the hold expired. The payment was released and the booking cancelled.
VOID_REJECTEDsupplierNoThe airline refused to void the ticket. The ticket stays valid; ask support about a refund instead.
VOID_NOT_SUPPORTEDsupplierNoThis supplier cannot void tickets automatically. The ticket stays valid; contact support.
NOTIFY_FAILEDsystemYesE-mail delivery failed; the ticket is still available in My trips.
CANCELLED_BY_USERcustomerNoThe traveller cancelled before paying.
INTERNALsystemYesUnexpected error. Check the worker logs with this correlation id.
API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)