Status & error reference

One place for every status value and error a client can receive, and (critically) which field or query returns it.

There is one status vocabulary. NEW, REVIEW, READY, REFUNDED and ERROR mean the same thing wherever you read them: on a refund candidate, on Quote.status, on Document.status, on Request.status, and in the status field of a webhook payload. They are always uppercase. A value you recognise on one of those fields is the same state on all of them.

Three things on this page are not that vocabulary, and are the only distinctions you still have to keep straight:

1. The quote-stage event values delivered by the refund_request.status_updated webhook (section 2); event progress, not an entity status.
2. The webhook delivery status (section 5); whether Deal Engine reached your endpoint, lowercase, nothing to do with refunds.
3. Coupon / segment / tax statuses (section 6): an airline-side vocabulary with its own per-PSS mapping.

How to read this page

1. Branch on the five-value enum for any refund state. Sections 1 and 3.
2. Treat unknown values as non-terminal and keep polling. Stop only on REFUNDED and ERROR.
3. Where a value set is not published, this page says so explicitly rather than guessing. Get the authoritative list for your tenant by introspecting the schema (see GraphQL conventions) or by asking Deal Engine.

🚧

Per-tenant configuration applies to rules, not to the status enum. Decisions, rejection behaviour and the non-refundable coupon list are configured per customer and recorded in your FSD (Functional Specification Document). The five status values are not; see Refund lifecycle & statuses.

Vocabulary map

1. The refund status enum

• Fulfillment only executes candidates in READY. NEW and REVIEW are never refunded.
• REFUNDED and ERROR are written only by the fulfillment engine. A client can never set a terminal status.
• Terminal statuses never transition again; re-submitting the same ticket does not change them.
• ERROR carries failure detail in its error history. Contact support with the ticket number when it is not actionable on your side.
• REFUNDED is unreachable in sandbox; fulfillment does not run there. See Testing & environments.

Why a refund sits in REVIEW: Deal Engine lacks an ingredient it needs to guarantee the quotation; for example the reservation was purged so the full quotation cannot be determined, or the fare rules are private and unreachable from the PSS. Full explanation: Refund lifecycle & statuses §2.

1.1 Legal transitions

1.2 Setting it

The quoteUpdateRequest input accepts refundCandidateStatus as a { from, to } envelope, alongside fields such as waiver, refundRoute and taxes. Payload conventions: API usage & integration.

mutation UpdateQuote($request: quoteUpdateRequest!, $requote: Boolean) {
    updateQuote(request: $request, requote: $requote)
}

{
  "request": {
    "ticketNum": "1282132019309",
    "refundCandidateStatus": { "from": "REVIEW", "to": "READY" }
  }
}

1.3 READY → REVIEW is the kill switch

Fulfillment re-verifies that a candidate is still READY immediately before executing it. Setting an approved candidate back to REVIEW therefore stops the refund from being executed; that is the supported way to hold a refund you have already approved.

2. Quote-stage event values (refund_request.status_updated)

Delivered as data.status on the refund_request.status_updated webhook. Despite the event name, its display name is "Quote updated"; it reports the progress of a quote request, not the status of an entity, which is why these values are longer strings and not the five-value enum.

Status values are delivered uppercase, exactly as shown.

• Use REFUND_CANDIDATE_READY / INSERTED_AND_CREATED_REFUND_CANDIDATE_READY as the trigger to read the quote from document(ticketNum); do not wait a fixed interval. See Request parameters explained.
• On ERROR_PROCESSING_REQUEST a fresh quote request can be safely submitted; Deal Engine has already exhausted its internal retries on transient failures. See Error handling.
• ERROR_PROCESSING_REQUEST is not the candidate status ERROR. Matching on "ERROR" here never fires.

3. refund_candidate.status_updated: the enum, delivered by webhook

The payload's status carries the section 1 enum verbatim, uppercase.

🚧

Write your handler so an unexpected status is logged and ignored rather than treated as an error, and do not assume the event only carries terminal outcomes; non-terminal READY and REVIEW deliveries do occur.

Delivery notes that affect state machines:

• Events triggered by Deal Engine internal operators are not delivered to client endpoints; a status can therefore change without a webhook arriving. Polling is the backstop.
• Delivery failures are logged in webhookEvents and do not affect the refund itself.

Payload shape, signing and verification: Webhooks guide and Webhook API Reference.

4. Optional explicit REJECTED quotation status

REJECTED is not part of the enum and not present by default. Rejection behaviour is configured per customer:

• Ask Deal Engine to enable the explicit REJECTED quotation status if you need a machine-checkable rejection signal. Until then, inspecting notes + amount is the only supported detection.
• A rejection is never transient. Never auto-retry a rejection; retrying returns the same result. Route to manual review with the note text. See Performance & uptime.

5. Webhook delivery status

Distinct from every refund status above: this describes whether Deal Engine successfully delivered an event to your endpoint. It is not a refund state.

Note the casing contrast: refund statuses are uppercase everywhere, including inside webhook payloads, while this delivery status appears lowercase. Compare case-sensitively and do not normalize one to the other.

6. Coupon, segment and tax statuses

Per-coupon refundability status is a separate, airline-side vocabulary. Deal Engine ships default mappings per PSS (Sabre, Amadeus) and customizes them per customer; including which coupon states count as open versus flown. Your mapping is aligned during the PoC and recorded in your FSD.

The reference table is authoritative on Refund lifecycle & statuses §3 and is not duplicated here: one table, one owner.

When parsing, note that these statuses appear both as short codes (O, OK, C, L, F, …) and as whole words in published samples ("couponStatuses": ["OPEN"], "segmentStatus": "OPEN", refundCandidateTaxes[].status: "OPEN"). Confirm the form your account receives against your FSD and one live response, and parse defensively for both.

7. Value sets referenced as literals but never enumerated

These fields appear in published request and response examples as bare string literals. The literals below are the only ones traceable to this documentation; they are examples, not enums. Do not treat any column as complete.

7.1 decision is configurable: how to get your list

decision is not a fixed enum: it is configured per customer and per flow. That is a legitimate design, not a documentation gap, but it means a hardcoded list will break. To obtain your active list:

1. At onboarding: Deal Engine provides your active decision list. This is the authoritative source.
2. Your FSD: the rule set agreed with Deal Engine defines every decision value and every rejection rule that can produce one.
3. Sandbox verification: exercise your test tickets and assert the decisions returned against your expected rule outcomes before go-live. See Testing & environments.

Your configuration may add variants (for example VOLUNTARY_BEFORE_DEPARTURE) or informational reasons (for example No open coupons found). Handle an unrecognised decision by routing to manual review; never by treating it as refundable.

Action per standard decision: the decision-to-action matrix on Refund lifecycle & statuses.

8. Error catalog

The API is GraphQL: errors arrive in the errors array, and a partial success can return both data and errors. Always inspect errors even when data is non-null.

{
  "errors": [
    { "message": "…", "path": ["login"], "extensions": { "code": "…" } }
  ],
  "data": null
}

8.1 Failure classes

🚧

Do not branch on extensions.code for login failures. A wrong email or password returns INTERNAL_SERVER_ERROR today; that is what the wire returns, verified against sandbox. The intended code for this case is UNAUTHENTICATED, so the value may change. Branch on the failure class you inferred from path plus data being null, and treat the message as human-readable only.

8.2 processRefund per-ticket results

processRefund does not fail the whole call when one ticket is bad. It returns a per-ticket summary, and success: false at the top level can still accompany tickets that were enqueued successfully.

Branch on the booleans, never on the strings. Deal Engine describes the per-ticket result values as enum values, but that enum is not published and cannot be introspected without authorization, so no list of them appears here. Match on top-level success, then per ticket on results[].success keyed by ticketNum; log message for humans only. See API usage & integration.

8.3 Retry policy

• Retry: network errors, HTTP 5xx, 429; exponential backoff.
• Do not retry: validation errors, authentication failures with fixed credentials, and any business rejection. A REJECTED decision does not change on retry.
• Deal Engine already retries transient PSS failures internally (up to 2 retries on network errors) before writing ERROR. Business refusals are never retried internally.
• After ERROR_PROCESSING_REQUEST at the quote stage, submitting a new quote request is safe.

Details: Error handling and Performance & uptime.

9. How to write a polling state machine safely

Webhooks are the recommended primary signal; polling is the backstop for the gaps (internal-operator changes are not delivered to client endpoints, and delivery can fail).

Rules

1. Key everything on ticketNum. Every status field, webhook payload and result row is keyed on the 13-digit ticket number.
2. Terminal set is a closed allow-list of two: REFUNDED and ERROR. Stop only on those. NEW, REVIEW, READY and any value you do not recognise keep the ticket in-flight.
3. Keep a default: branch. Log and continue rather than erroring: which statuses fire a webhook is only partly documented (section 3), and decisions are per-tenant (section 7.1).
4. Do not confuse the two vocabularies. ERROR_PROCESSING_REQUEST on the quote-stage event is a failed quote attempt, not the candidate status ERROR.
5. Poll every 30–60 seconds. Execution can take ~2 minutes; faster polling adds nothing. Add a wall-clock timeout and escalate to support rather than polling forever.
6. Do not read the outcome from processRefund. Acceptance ≠ outcome, with or without Sync: true.
7. Reconcile on the executed amounts, never on the quote estimate; the fare, taxes, penalty and total to refund recorded when the refund executes, all gross. See Refund amounts & reconciliation.
8. Separate "rejected" from "failed". A rejection is a business outcome that must not be retried; an ERROR may be worth investigating with support. Detect rejection via the explicit REJECTED quotation status if enabled, otherwise via notes + a zero refund amount.
9. Make webhook handlers idempotent. Dedupe on eventId; the same status may arrive more than once, and polling may observe a transition the webhook also reports.
10. In sandbox, target READY, not REFUNDED. Fulfillment does not run there, so REFUNDED is unreachable by design.

Recommended shape

on createQuote accepted:
    mark ticket QUOTING

on refund_request.status_updated (or poll):
    *_REFUND_CANDIDATE_READY  -> read document(ticketNum).quote, mark QUOTED
    ERROR_PROCESSING_REQUEST  -> mark QUOTE_FAILED (a fresh createQuote is safe)
    anything else             -> log, stay QUOTING

when QUOTED:
    rejected (explicit REJECTED status, or notes + zero amount)
                              -> mark REJECTED, route to manual review, STOP
    status REVIEW             -> route to your validation step; on approval
                                 updateQuote REVIEW -> READY
    status READY              -> call processRefund, mark SUBMITTED

when SUBMITTED (webhook, plus poll every 30-60s):
    REFUNDED                  -> mark DONE, reconcile on executed amounts, STOP
    ERROR                     -> mark FAILED, capture error history, STOP
    anything else (READY, REVIEW, unknown)
                              -> stay SUBMITTED
    elapsed > your timeout    -> escalate to support with ticketNum, keep polling

Acceptance is not an outcome. A successful processRefund response means the ticket passed basic validation and entered the queue. Sync: true on processRefund only delays the response; the body remains the enqueue acknowledgment. Treat REFUNDED, never the acceptance response, as confirmation. See Request parameters explained.

10. Remaining open items

Each item below is unresolved in the published documentation; do not resolve it by assumption.

Related pages

• Refund lifecycle & statuses; the lifecycle narrative, coupon status table, and decision matrix
• Refund amounts & reconciliation; which amount is authoritative
• Webhooks guide and Webhook API Reference; payloads, signing, delivery history
• API usage & integration; full request/response examples
• Request parameters explained; the Sync header and commonly misread fields
• Error handling and Authentication & authorization
• GraphQL conventions; filters, pagination, and reading the schema
• Testing & environments; what can and cannot reach a terminal status in sandbox
• What is a quote? · What is a document? · What is a request?