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.
{
"status": "error",
"message_code": "FormError",
"status_code": 422,
"message": "Form error",
"message_human": "Form error",
"data": {
"flights": [{"departure_date": ["Not a valid date."]}]
}
}| Field | Description |
|---|---|
status | Always the literal string "error" for error responses. |
message_code | Machine-readable error category (e.g. FormError, NotFound). Use this for branching. |
status_code | Numeric HTTP status code mirrored in the body for convenience. |
message / message_human | Short human-readable message; safe to log, sometimes safe to surface. |
data | Field-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):
{
"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:
{
"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 successful201- Resource created
4xx Client Errors
401- Unauthorized (missing or invalid X-API-KEY)404- Resource not found422- Form validation error (usedatafor field-level details)429- Rate limit exceeded
5xx Server Errors
500- Internal server error502- Bad gateway (upstream airline system unavailable)503- Service unavailable
Common message_code values
message_code | HTTP | What it means |
|---|---|---|
FormError | 422 | Request body failed validation. Field-level details in data. |
NotFound | 404 | The 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_reason | Category | Recommended action |
|---|---|---|
200, 220, 221, 222 | Booking reference, ticket or passenger-name validation | Check the supplied booking details before deciding whether to submit again. |
201 | No response to a request for more information | Review the requested fields and contact support about the next step. |
202, 208 | Passenger or flight mismatch | Verify the passengers and itinerary against the booking. |
300, 301 | Check-in not yet available or temporarily unavailable | Confirm timing and next action with support; a failed status does not promise another attempt. |
400 | Check-in window expired | Check the departure and check-in deadline; seek an alternative with the airline if needed. |
401, 402, 410, 411 | Online check-in unavailable, flight cancelled, or seats unavailable | Ask support to confirm the specific result and the available options. |
420–423 | Airport-desk classification | 420 is the generic classification. Ask support to confirm the underlying reason before advising a passenger that airport check-in is required. |
500, 503, 504, 505 | Technical or processing timeout result | Contact 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
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.
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
@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 retryDebugging 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.