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.failureCodeonce 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"
}
}codeis stable. Match on it in your code.messageis for people and may change. Show it, log it, do not parse it.requestIdequals thex-request-idresponse header and finds the call in the request log.issuesis present only forVALIDATION_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.
| Code | Category | Retryable | What to do |
|---|---|---|---|
PASSENGER_MIX_MISMATCH | customer | No | Passengers must match the search (adults, children, infants). Search again with the right mix. |
NAME_NOT_LATIN | customer | No | Names must use Latin letters exactly as in the passport. |
PASSENGER_AGE_INVALID | customer | No | Age does not match the passenger type on the date of the last flight. |
INFANTS_EXCEED_ADULTS | customer | No | Each infant must travel with its own adult. |
PASSPORT_EXPIRED | customer | No | The passport expires before the trip ends. Use a valid passport. |
PRICE_CHANGED | supplier | No | The airline changed the price. Ask the traveller to confirm the new price. |
PRICE_REJECTED | customer | No | The traveller declined the new price. |
PRICE_CONFIRMATION_TIMEOUT | customer | No | The traveller did not answer the price change in time. |
SOLD_OUT | supplier | No | This fare sold out. Offer the next cheapest flight. |
SUPPLIER_TIMEOUT | supplier | Yes | The supplier did not answer in time; retried automatically. |
SUPPLIER_REJECTED | supplier | No | The supplier refused the request; its message says why. Search again or choose another flight. |
PAYMENT_DECLINED | payment | No | The bank declined the card. The traveller can try another card or wallet. |
PAYMENT_TIMEOUT | customer | No | No payment arrived before the hold expired; the booking was cancelled. |
ISSUE_REJECTED | supplier | No | The airline refused to issue. The hold was released and the booking cancelled. |
ISSUE_STATUS_UNKNOWN | supplier | Yes | Issue timed out; checking status before trying again so no ticket is issued twice. |
ISSUE_NOT_REQUESTED | customer | No | Payment was held, but nobody asked to issue the ticket before the hold expired. The payment was released and the booking cancelled. |
VOID_REJECTED | supplier | No | The airline refused to void the ticket. The ticket stays valid; ask support about a refund instead. |
VOID_NOT_SUPPORTED | supplier | No | This supplier cannot void tickets automatically. The ticket stays valid; contact support. |
NOTIFY_FAILED | system | Yes | E-mail delivery failed; the ticket is still available in My trips. |
CANCELLED_BY_USER | customer | No | The traveller cancelled before paying. |
INTERNAL | system | Yes | Unexpected error. Check the worker logs with this correlation id. |