Error Handling

A robust integration handles errors gracefully. This guide covers all error types you may encounter and how to handle them properly.

Error Response Format

Errors come in two flavours: HTTP-level errors emitted by the API (for auth, validation, missing resources) and check-in-level failures emitted as part of a normal 200 response when a check-in finishes in the failed state.

HTTP error envelope

Errors returned by the Corp API use the envelope below. The portal endpoint can reject a request before forwarding it, for example for an invalid portal key, restricted route or rate limit; those errors use {detail: ...}, where detail can be a string or object. Check the HTTP status first and handle either shape.

HTTP error envelope
json
{
  "status": "error",
  "message_code": "FormError",
  "status_code": 422,
  "message": "Form error",
  "message_human": "Form error",
  "data": {
    "flights": [{"departure_date": ["Not a valid date."]}]
  }
}
FieldDescription
statusAlways the literal string "error" for error responses.
message_codeMachine-readable error category (e.g. FormError, NotFound). Use this for branching.
status_codeNumeric HTTP status code mirrored in the body for convenience.
message / message_humanShort human-readable message; safe to log, sometimes safe to surface.
dataField-level details when applicable (validation errors), or null.

The direct Corp API's 401 response from missing/invalid auth is a slightly older shape that does NOT use this envelope (the portal's own 401 uses detail):

401 unauthorized response (auth-only)
json
{
  "error": "unauthorized",
  "message": "Missing X-API-KEY header"
}

Check-in failure shape

When a check-in completes unsuccessfully, the API returns the check-in as a 200 response (the request itself succeeded) with status: "failed" and a fail_reason numeric code:

Failed check-in
json
{
  "id": 504061687271,
  "status": "failed",
  "fail_reason": 200,
  "data": { /* ... */ },
  "files": []
}

Webhooks in the Corp API format (the default for new webhooks, the Sandbox API settings webhook and direct Corp API accounts) deliver this same check-in object as {status, checkin}. Webhooks in the Portal format deliver a summary instead, as {event, timestamp, customer_id, data} (see Webhooks).

HTTP Status Codes

2xx Success

  • 200 - Request successful
  • 201 - Resource created

4xx Client Errors

  • 401 - Unauthorized (missing or invalid X-API-KEY)
  • 404 - Resource not found
  • 422 - Form validation error (use data for field-level details)
  • 429 - Rate limit exceeded

5xx Server Errors

  • 500 - Internal server error
  • 502 - Bad gateway (upstream airline system unavailable)
  • 503 - Service unavailable

Common message_code values

message_codeHTTPWhat it means
FormError422Request body failed validation. Field-level details in data.
NotFound404The referenced resource (check-in, passenger, file) does not exist.

fail_reason codes for failed check-ins

When status is failed, branch on fail_reason, a numeric result code in production responses and Corp-format webhooks. Some older or sandbox responses may use numeric strings; normalize them before comparing. These codes are separate from HTTP status codes. Common codes include:

fail_reasonCategoryRecommended action
200, 220, 221, 222Booking reference, ticket or passenger-name validationCheck the supplied booking details before deciding whether to submit again.
201No response to a request for more informationReview the requested fields and contact support about the next step.
202, 208Passenger or flight mismatchVerify the passengers and itinerary against the booking.
300, 301Check-in not yet available or temporarily unavailableConfirm timing and next action with support; a failed status does not promise another attempt.
400Check-in window expiredCheck the departure and check-in deadline; seek an alternative with the airline if needed.
401, 402, 410, 411Online check-in unavailable, flight cancelled, or seats unavailableAsk support to confirm the specific result and the available options.
420–423Airport-desk classification420 is the generic classification. Ask support to confirm the underlying reason before advising a passenger that airport check-in is required.
500, 503, 504, 505Technical or processing timeout resultContact support with the check-in ID and exact result code.

For successful check-ins, fail_reason is 100 (with boarding pass) or 101 (without). For idle check-ins it is null.

Keep the exact code: 420 is not interchangeable with 400. A result classification does not by itself prove the underlying cause. For unknown codes, retain the check-in ID and contact support rather than guessing or automatically submitting a duplicate.

Error Handling Best Practices

1. Always Check for Errors

Python error handling
python
import requests

def create_checkin(data):
    response = requests.post(
        fclass="token-string">"{BASE_URL}/checkins",
        headers={class="token-string">"X-API-KEY": API_KEY},
        json=data,
        timeout=30,
    )

    if response.status_code in (200, 201):
        return response.json()

    body = response.json() if response.headers.get(class="token-string">"content-type", class="token-string">"").startswith(class="token-string">"application/json") else {}

    class=class="token-string">"token-comment"># 401 uses a slightly different envelope (legacy)
    if response.status_code == 401:
        raise PermissionError(body.get(class="token-string">"message", class="token-string">"Unauthorized"))

    class=class="token-string">"token-comment"># Surface rate limiting to the caller; do not recursively resubmit.
    if response.status_code == 429:
        retry_after = response.headers.get(class="token-string">"Retry-After", class="token-string">"not supplied")
        raise RuntimeError(fclass="token-string">"Rate limited; Retry-After: {retry_after}")

    class=class="token-string">"token-comment"># All other 4xx/5xx: standard envelope with message_code
    code = body.get(class="token-string">"message_code")
    if code == class="token-string">"FormError":
        class=class="token-string">"token-comment"># Field-level details under body[class="token-string">"data"]
        raise ValueError(fclass="token-string">"Validation failed: {body.get('data')}")
    if code == class="token-string">"NotFound":
        raise LookupError(body.get(class="token-string">"message", class="token-string">"Not found"))

    raise RuntimeError(fclass="token-string">"API Error {response.status_code}: {body.get('message') or 'Request failed'}")

2. Reconcile Uncertain Results Before Retrying

A timeout, connection failure or 5xx response does not prove that a create request was rejected: it may already have been accepted. Keep your request reference and check the account's check-in list or contact support before submitting it again. Do not assume that remote_id makes repeated POST requests idempotent. For a clear 429 response, respect Retry-After before any later attempt. Both examples make one request and return errors to the caller instead of retrying automatically.

JavaScript single-attempt request
javascript
async function createCheckin(data) {
  class=class="token-string">"token-comment">// A rejected fetch propagates to the caller; do not repeat the POST here.
  const response = await fetch(class="token-string">`${BASE_URL}/checkins`, {
    method: class="token-string">'POST',
    headers: {
      class="token-string">'X-API-KEY': API_KEY,
      class="token-string">'Content-Type': class="token-string">'application/json'
    },
    body: JSON.stringify(data)
  });

  if (response.ok) return await response.json();

  const error = await response.json().catch(() => ({}));
  if (response.status === 429) {
    const retryAfter = response.headers.get(class="token-string">'Retry-After') || class="token-string">'not supplied';
    throw new Error(class="token-string">`Rate limited; Retry-After: ${retryAfter}`);
  }

  throw new Error(class="token-string">`API Error ${response.status}: ${error.message || 'Request failed'}`);
}

3. Handle Webhook Errors Gracefully

Webhook error handling
python
@app.route(class="token-string">'/webhooks/checkin', methods=[class="token-string">'POST'])
def handle_webhook():
    try:
        payload = request.json
        status = payload.get(class="token-string">'status')
        checkin = payload.get(class="token-string">'checkin', {})

        if status == class="token-string">'failed':
            class=class="token-string">"token-comment"># Production uses numbers; tolerate legacy numeric strings.
            raw_reason = checkin.get(class="token-string">'fail_reason')
            fail_reason = int(str(raw_reason)) if str(raw_reason).isdigit() else None

            if fail_reason in (200, 220, 221, 222):
                class=class="token-string">"token-comment"># Verify the booking reference, ticket or passenger name.
                notify_customer(
                    checkin.get(class="token-string">'remote_id'),
                    class="token-string">"Please verify your booking details"
                )
            else:
                class=class="token-string">"token-comment"># Preserve the specific code (including 420 or 503).
                class=class="token-string">"token-comment"># Failed is terminal: do not assume an automatic retry.
                alert_support(checkin_id=checkin.get(class="token-string">'id'), fail_reason=fail_reason)

        return class="token-string">'OK', 200

    except Exception as e:
        log_error(fclass="token-string">"Webhook error: {e}")
        return class="token-string">'Error', 500  class=class="token-string">"token-comment"># We'll retry

Debugging Tips

Check the Response Body

Record the check-in ID, status and exact result code for troubleshooting. Avoid logging passenger data, API keys or boarding-pass URLs.

Verify Data Format

Dates must be YYYY-MM-DD, airline codes must be valid IATA codes, and names must match the booking exactly.

Test in Sandbox First

Use the sandbox terminal to test requests before implementing in code.

Check Webhook Delivery History

For webhooks in Settings > Webhooks, the delivery history shows every delivery, the HTTP status or error of its last attempt, and its next retry. For direct Corp API webhooks, check your endpoint's own request logs.

Getting Help

If you encounter an error you can't resolve:

  • Check this documentation and the API reference.
  • Reproduce the error against the sandbox if possible (Z0 scenarios cover most failure modes).
  • Email support with the full request body, the response body, and the timestamp; we'll trace it.