Error Handling & Troubleshooting

Every PolarHub response carries a ResultMessage object that tells you exactly what happened. This page explains how to read it, how to resolve the errors you'll see most often, when to retry, and how to escalate if you're stuck.

Read ResultMessage.Code → Is it 00000? ──yes──▶ success
                                │
                                no
                                ▼
        Find the code below → apply the fix → retryable? ──no──▶ fix & resubmit
                                                  │
                                                 yes ──▶ retry with backoff
                                                  │
                              still failing / code not listed ──▶ Reporting an Issue

1. The error model

PolarHub surfaces errors in two layers:

Transport (HTTP status) — whether the request reached and was accepted by PolarHub.

Application (ResultMessage) — the authoritative business result, in the response body. Always read ResultMessage first: a 200 OK can still carry a business error.

ResultMessage structure

"ResultMessage": {
  "Code": "50243",
  "Message": "Invalid or Expired Offer"}

Code — a 5-digit string. 00000 = success; any other value = error.

Message — human-readable text. For airline-origin errors, the carrier's own message is passed through verbatim.

Code families (read the leading digits to know where to look):

Range	Family	What it means
`00000`	Success	Request succeeded
`501xx`	AirShopping validation	Missing/invalid search fields
`502xx`	Order / booking / ticketing	Required fields and booking-state errors
`503xx`	Price / order / issue validation	Required fields for OfferPrice / OrderCreate / issue
`505xx`	Airline-dependent	Waitlist, airline passthrough
`59395` / `95005`	Aggregator / upstream	Airline response unclear or timed out
`xx297` / `xx397`	Internal build/convert	Result build / message convert error
`99999`	Uncaught exception	Unhandled system error

⚠️ HTTP-layer conventions (draft — please confirm before publishing): auth/signature failures and clock skew beyond ±120s → 401/403; rate limiting → 429; gateway/infra → 5xx. Application errors are typically returned as 200 OK with a non-00000 ResultMessage.Code. (These mappings need a final check against the gateway config.)

2. Common errors & how to resolve them

🔑 Authentication

Signature or timestamp rejected (request never reaches the business layer).
Fix: Rebuild the signature using the sample code in the Authentication (HMAC) guide, and keep your clock NTP-synced (requests are valid within ±120s).

📝 Request validation — `501xx`, `502xx`/`503xx` "value is required"

A field is missing or malformed (e.g., 50102 Origin required, 50117 invalid Cabin, 50119 too many passengers, 50120 invalid PTC, 50233 OrderID required).
Fix: Correct the named field and resubmit. Not retryable as-is — the same request will fail again.

🎟 Offer lifecycle

Code	Meaning	What to do
50243	Invalid or Expired Offer	The offer expired — run a fresh AirShopping → OfferPrice and use the new offer.
50332	OfferPrice failed (cache off)	Re-shop to refresh the offer cache, then price again.
50244	OrderItem already ticketed	Stop — the item is already issued. Verify with OrderRetrieve.
50258	Multiple Order with same OfferID	Don't reuse an `OfferID` across orders; create from a fresh offer.

📑 Booking / ticketing state

Code	Meaning	What to do
50202	Booking created, airline response error (BA timeout)	Do not re-book. The PNR exists — retrieve it with the OrderID.
50240	Passenger / ticket count mismatch	PolarHub auto-cancels the PNR. Rebook and reissue.
50257	PNR not created (supplier PNR only)	Treat as failed — the airline did not create the PNR. Rebook.
50241	PNR currently being updated	Transient — wait briefly and retry.
50250 / 50201	PNR previously cancelled	Already cancelled — no further action.
50238	Cannot check order status	Retrieve the order for the current state instead of retrying.

✈ Airline / aggregator

Code	Meaning	What to do
95005	Aggregator Service Error (e.g. timeout)	Transient upstream issue — retry with backoff.
59395	Service error (timeout / 500)	Transient — retry with backoff.
50599	Airline response error (passthrough)	Read the airline's message in `Message`; retry only if it's transient, otherwise fix per the message.
50501	Waitlist is closed	Not retryable — the airline closed the waitlist.
50235	No access to overbook flight	Not retryable — overbooking not allowed by the airline.

🛫 Carrier-specific

Code	Meaning	What to do
50261	KE order not cancelled	Proceed with KE's manual refund process.
50330	NDC order modified externally (FLX)	Retrieve the latest order state before acting.
50262	Request conflict with another operation	Transient — retry.

3. Retry guidance

Match the error to one of four behaviors — retrying a non-transient error just repeats the failure.

Behavior	When	Codes (examples)
🔁 Retry with backoff	Transient upstream/system or short-lived lock	`95005`, `59395`, `99999`, `50241`, `50262`
🔎 Don't retry — retrieve	The action may have partially succeeded; fetch the real state	`50202`, `50238`, `50330`
🛑 Don't retry — fix & resubmit	Deterministic: bad input or terminal state	all `501xx`/`50x` "required", `50243`, `50244`, `50250`, `50501`, `50235`
✈ Airline-dependent	Outcome depends on the carrier's own message	`50599`

Backoff: start ~1s and double up to a sensible cap (e.g., 3–5 attempts). Reuse the same TransactionID across retries of the same logical operation so the attempts trace together in our logs.

4. Still stuck? Report it

If the error persists after the steps above, or the code isn't listed / the behavior is unexpected:

Capture the ResultMessage (Code + Message) and the time (with timezone).

Copy your Transaction ID and the full request/response payload of the failing call.

Follow Reporting an Issue — the PolarHub template lists exactly what to attach.

📮 Reports go to halosync_support@halocorp.kr. For general questions, see FAQ & Contact.

5. Full error code reference

Complete list of ResultMessage.Code values. Message is the literal string returned by the API.

Code	Message	Remarks
00000	success
99999	Uncaught Exception	Unhandled system error
95005	Aggregator Service Error	Airline responded in a way that prevented error classification, so the Aggregator could not process it. Example: timeout
50101	It is not a valid Origin value
50102	The 'Origin' value is required.
50103	It is not a valid Destination value
50104	The 'Destination' value is required.
50105	It is not a valid Triptype value
50106	The 'TripType' value is required.
50107	It is not a valid mtDeparture value
50108	If the itinerary type is MT, the mtDeparture value is required.
50109	It is not a valid mtArrival value
50110	If the itinerary type is MT, the mtArrival value is required.
50111	It is not a valid DepartDate value
50112	It is not a valid mtDepartDate value
50113	If the itinerary type is MT, the mtDepartdate value is required.
50114	It is not a valid ReturnDate value
50115	It is not a valid mtArrivalDate value
50116	If the itinerary type is MT, the mtArrivalDate value is required.
50117	It is not a valid Cabin value	Y: economy, W: premium economy, C: business, F: first
50118	The 'Passenger' value is required.
50119	The maximum number of passengers that can be requested is {} persons.
50120	It is not a valid PTC value
50121	If the itinerary type is RT or OW, the ReturnDate value is required.
50122	The array sizes of MtDeparture, MtArrival, and MtDepartDate must be the same.
50150	Results build error
50152	Can't find ShoppingResponse Data
50153	Not found airline route.
50154	Not found airline provider.
50199	No query results.
50201	Invalid PNR Cancel: PNR previously cancelled
50202	Your booking has been created successfully. Please retrieve it using the OrderID	BA timeout: booking created but airline response error. Retrieve with OrderID.
50203	Ticket issue fail
50204	The 'AgencyID' value is required.
50205	The 'Recipient' value is required.
50206	The 'Passengers' value is required.
50207	The 'PassengerID' value is required.
50208	The 'Ptc' value is required.
50209	The 'Gender' value is required.
50210	The 'BirthDate' value is required.
50211	The 'Name' value is required.
50212	The 'NameTitle' value is required.
50213	The 'Surname' value is required.
50214	The 'GivenName' value is required.
50215	The 'Offer' value is required.
50216	The 'OfferID' value is required.
50217	The 'Owner' value is required.
50218	The 'OfferItems' value is required.
50219	The 'OfferItemID' value is required.
50220	The 'Query' value is required.
50221	The 'Offers' value is required.
50222	The 'Flights' value is required.
50223	The 'OriginDestinationKey' value is required.
50224	The 'Segments' value is required.
50225	The 'SegmentKey' value is required.
50226	The 'FareBasisCode' value is required.
50227	The 'PriceClassName' value is required.
50228	The 'FareRefKey' value is required.
50229	The 'ResponseID' value is required.
50230	The 'Order' value is required.
50231	The 'Action' value is required.
50232	It is not a valid 'Action' value ex) issue or refund or void
50233	The 'OrderID' value is required.
50234	The 'BookingReference' value is required.
50235	No access to overbook flight.	Overbooking not allowed by the airline
50236	The Order has not been cancelled, Unable to update ticket status from airline
50237	The Order has not been cancelled, Same day refunds not allowed
50238	Cannot check the status Order, please retrieve the order for details
50239	Invalid PromotionCd
50240	Passenger count and ticket document count is not matched.	If ticket count ≠ passenger count, PolarHub automatically cancels the PNR
50241	PNR {PNRADDR} currently being Updated	PNR is being updated — retry later
50242	Cannot make fareRule information
50243	Invalid or Expired Offer	Returned when using an expired offer
50244	OrderItem {1} specified already ticketed	Ticket issuance requested for an already-ticketed order
50245	The 'OrderID' or 'BookingReference' value is required.
50246	Can't find OrderID
50247	Incorrect 'FlightQuery' information
50248	Incorrect 'ResponseID'
50249	Can't find Order information
50250	PNR previously cancelled	PNR already cancelled at the airline
50252	Deletion not allowed	Involuntary change cancellation not allowed
50253	Invalid response to TicketImageRQ	Airline response invalid
50255	The 'PassengerAssociationReference' value is required.	Required when an INF passenger must reference a guardian
50256	Cannot add duplicate seat elements for the same traveler and segment.	Duplicate seat assignment attempted
50257	PNR not created	PNR not issued at the airline; only the supplier PNR was created
50258	Multiple Order with the same OfferID
50259	Invalid Country Code : CountryOfIssuance	Country code longer than 3 characters
50260	Can't find OrderReshop Response Data
50261	The KE Order has not been cancelled, please proceed with the manual refund process.	KE refund restriction
50262	Request conflict with another operation. Please try again.
50295	{messageName}, service error
50296	{messageName}, Polarpie Message Convert Error
50297	Result build error
50298	Segment status is HL
50299	No query results
50301	The 'AgencyID' value is required.
50302	The 'Recipient' value is required.
50303	The 'Passengers' value is required.
50304	The 'PassengerID' value is required.
50305	The 'Ptc' value is required.
50306	The 'Gender' value is required.
50307	The 'BirthDate' value is required.
50308	The 'Name' value is required.
50309	The 'NameTitle' value is required.
50310	The 'Surname' value is required.
50311	The 'GivenName' value is required.
50312	The 'Offer' value is required.
50313	The 'OfferID' value is required.
50314	The 'Owner' value is required.
50315	The 'OfferItems' value is required.
50316	The 'OfferItemID' value is required.
50317	The 'Query' value is required.
50318	The 'Offers' value is required.
50319	The 'Flights' value is required.
50320	The 'OriginDestinationKey' value is required.
50321	The 'Segments' value is required.
50322	The 'SegmentKey' value is required.
50323	The 'FareBasisCode' value is required.
50324	The 'PriceClassName' value is required.
50325	The 'FareRefKey' value is required.
50326	If TicketDateTime set then 'Date' value is required.
50327	If TicketDateTime set then 'Time' value is required.
50328	The 'ResponseID' value is required.
50329	Need an OrderID or OfferID.
50330	NDC Order discrepancy error. Order has been modified externally.	Order modified externally (FLX only)
50331	Can't find ResponseID
50332	OfferPrice request failed due to cache control being disabled.
50396	{messageName}, Polarpie Message Convert Error
50397	Result build error
50399	No query results
59395	{messageName}, service error	Airline response unclear and BE cannot process (e.g. timeout, 500 error)
50501	Waitlist is closed	Airline waitlist is closed
50599	{Owner}, {airline response message}, Airline response error	The airline's own error message is passed through. When the NDC API returns an error regardless of content, it is surfaced as 50599.

Error Handling & Troubleshooting

1. The error model#

2. Common errors & how to resolve them#

🔑 Authentication#

📝 Request validation — 501xx, 502xx/503xx "value is required"#

🎟 Offer lifecycle#

📑 Booking / ticketing state#

✈ Airline / aggregator#

🛫 Carrier-specific#

3. Retry guidance#

4. Still stuck? Report it#

5. Full error code reference#