Fallback and Resilience

Tools go down. APIs break. Have a backup plan for every search.

| Primary Tool | When It Fails | Fallback | |-------------|---------------|----------| | Duffel | API error or timeout | Ignav, Google Flights skill, Skiplagged | | Ignav | API error | Duffel, Google Flights skill, Skiplagged | | Google Flights | agent-browser error | Duffel, Ignav, Skiplagged | | Skiplagged | 502/timeout (Cloudflare issues) | Kiwi.com MCP, Duffel, Ignav | | Kiwi.com | Server error | Skiplagged MCP, Duffel | | Seats.aero | API error or stale data | Check airline website directly, use Duffel for GDS inventory | | Southwest | SW rate limiting or bot detection | Wait a few minutes and retry. Use Docker (ghcr.io/borski/sw-fares) if running locally fails. Google Flights skill for SW cash prices as a fast fallback. | | SerpAPI | Rate limit (100/mo free) | Trivago for hotels, web search for destination discovery | | Trivago | Server error | LiteAPI for hotels, SerpAPI Google Hotels | | LiteAPI | Auth error (401) | Trivago MCP, SerpAPI Google Hotels | | Airbnb | Scraping blocked | Suggest user check airbnb.com directly | | AwardWallet | API error | Ask user for their balances directly | | Ferryhopper | Server error | SerpAPI or web search for ferry routes | | Atlas Obscura | Script error | Web search for "unusual things to do in destination]" | | Chase Travel | Login failure or CSRF issues | Use Duffel/Ignav for cash prices. Note that Points Boost and Edit detection are Chase-only. | | Amex Travel | Login failure or form changes | Use Duffel/Ignav for cash prices. Note that IAP fares and FHR/THC detection are Amex-only. | | Deutsche Bahn (db-vendo) | Library error or bahn.de outage | SerpAPI Google Travel Explore, web search for "DB train origin] dest]", or fall back to confirming flight options instead. | | Wikipedia airports | API rate limit (rare) or page missing | Web search "airport name] airlines destinations" returns the same data via Google. | | Fare tool says "no results" | Could be no availability OR no service | Use wikipedia-airports to confirm whether the route is flown at all. If Wikipedia lists the destination as served, fare tools have no availability on that date. If Wikipedia doesn't list it, the route doesn't exist. Saves you from asking the user to retry searches that can never succeed. |

General Rules

• If an MCP server returns an error, try the curl-based skill equivalent (or vice versa).
• If a paid API hits its rate limit, switch to a free alternative.
• Never give up after one tool fails. Always try at least one fallback.
• Tell the user which source you used. "Skiplagged was down, so I checked Kiwi.com instead."

Never Claim MCP Is Unavailable Without Calling It

Do not declare an MCP server "not available" from a glance at your tool list — attempt an actual tool call first. The Skiplagged and Kiwi servers need no API keys and are wired into every supported harness config; a session launched from the repo directory has them. If a call genuinely fails, quote the error to the user and then fall back.

And when falling back, never silently substitute ad-hoc browser scraping for the toolkit's sources. Improvised scraping (e.g., driving a browser to Google Flights by hand) produces prices that miss most of the market. If you're ever reduced to it, say so explicitly and label every price from it as low-confidence: "MCP sources were unreachable, so this is a single scraped quote — treat it as a ceiling, not a market price."

IP Allowlist Errors (Common First-Time Failure)

Several APIs in the toolkit enforce IP allowlists on the developer key. If you see one of these error signatures, do NOT rabbit-hole on auth or quotas. Suggest the user whitelist their IP first.

| API | Error Signature | Whitelist Page | |---|---|---| | AwardWallet | {"error": "access_denied", "code": "IP_DENIED"} | https://business.awardwallet.com/profile/api | | TripAdvisor | User is not authorized to access this resource with an explicit deny | https://www.tripadvisor.com/developers |

Diagnostic flow when an API call fails with an auth-shaped error on first use:

1. Run curl ifconfig.me to get the user's current outbound IP.
2. Check if the failure signature matches an IP allowlist (table above or similar phrasing like "explicit deny" / "IP_DENIED" / "not whitelisted").
3. Tell the user: "This looks like an IP allowlist issue, not a key issue. Add <their IP> at <provider page>, wait 1-5 min for AWS edge cache propagation, then retry."
4. While they whitelist, gracefully degrade: continue without that data source, noting it's pending. Don't block the rest of the workflow.
5. Multi-IP gotcha: residential CGNAT, VPN exits, hotel wifi, and travel locations all need separate entries. If they hit the same error from a new network, the IP changed.

"No Cached Availability" Is Not the Final Word

When Seats.aero returns no results for a route + program combination, that means Seats.aero has not scraped it recently. It does NOT mean the award is unbookable. When a reachable program shows no cached results, search the airline's website directly before declaring awards dead.

Patchright-Based Skills (Southwest, AA, Chase, Amex, TaW)

These hit websites directly with an undetected browser. Common failure modes:

• Login form changed. The site updated its DOM. Selectors break. Update the skill.
• 2FA loop. Some skills (AA, Amex) handle email 2FA. Make sure 2FA delivery method is set correctly in the account.
• Bot detection. If you get "unusual activity" or CAPTCHA pages, the persistent profile may be flagged. Try a fresh profile or wait an hour.
• Headless detection. Patchright runs headed. If running locally fails, use the Docker image (xvfb provides virtual display).

Docker Image Failures

If docker pull ghcr.io/borski/... fails:

• unauthorized: Run docker logout ghcr.io then retry. Or login with a GitHub PAT that has read:packages. Or build locally with docker build -t <tag> skills/<skill>/.
• Network timeout: Retry with --platform linux/amd64 if you're on ARM and getting checksum mismatches.