Errors

Every failed call answers an HTTP status of 400 or more and a JSON body of the same shape, whichever endpoint it came from. Write one error handler against this page and it works for flights, hotels, eSIMs and the account.

The error body

{
  "environment": "sandbox",
  "success": false,
  "errors": [
    {
      "code": "invalid_airport_code",
      "type": "validation_error",
      "title": "Invalid airport code",
      "message": "origin must be a 3-letter IATA code; got 'ALGG'.",
      "field": "origin",
      "details": {},
      "documentation_url": "https://fx-port.com/docs/errors#invalid_airport_code"
    }
  ],
  "meta": { "request_id": "req_8f3a9c1d2e4b", "status": 400 },
  "request_id": "req_8f3a9c1d2e4b"
}

Check success, not only the status

A few post-booking endpoints (paying an order, an order quote, a cancellation quote, confirming a cancellation) answer a refusal of the supplier with HTTP 200 and "success": false. The body then carries the same errors array. Treat a response as successful only when the status is 2xx and success is not false.

data = response.json()
if not response.ok or data.get("success") is False:
    error = (data.get("errors") or [{}])[0]
    raise ApiError(response.status_code, error.get("code"), error.get("message"), data.get("request_id"))

What to do about each type

Codes

A code is a short, stable snake_case word (invalid_airport_code, read_write_permission_required, hotel_not_bookable_in_sandbox). Three kinds exist:

• Specific codes name the problem. They are listed in the catalogue below and on the page of each endpoint. New ones can be added; the ones that exist are never renamed.
• Generic codes (bad_request, not_found, conflict, internal_error ...) stand for the HTTP status when no more specific code applies. Read the message.
• Supplier codes pass through what the airline, hotel or eSIM supplier answered, with type: "supplier_error": sometimes a number ("4926"), sometimes a word (validation_type). They are not in the catalogue because the suppliers own them. Handle them by type, and show the message when you need to tell a human.

Write your handler with a switch on the codes you care about and a default that falls back on type.

HTTP statuses

Errors that do not come from the API

The API is served through Cloudflare. A few answers are generated before your request reaches FX-Port, and they are not JSON:

• 403 with an HTML page and "error code: 1010": Cloudflare blocked the default User-Agent of your HTTP library. The default agents of Python's urllib and of Perl's libwww-perl are blocked. Send a User-Agent of your own (for example my-company-booking/1.0). The other clients we tested work with their default agent: curl, Wget, Python requests, httpx and aiohttp, Node fetch and axios, Go, Java, OkHttp, Apache HttpClient, PHP Guzzle, Ruby, Dart, Postman, Insomnia and HTTPie.
• 301 from http://: use https:// only.
• 307 without a body on a URL that ends with a slash: remove the trailing slash.
• 502, 504 or 524 with an HTML page: the edge could not reach the API in time. Treat them like any other temporary failure and retry with backoff.

Parse the body only when the Content-Type is application/json.

Retrying safely

For everything you may repeat, use exponential backoff with jitter and honour Retry-After:

import random
import time

import requests

RETRYABLE = {429, 500, 502, 503, 504}


def call_with_retry(method, url, attempts=5, **kwargs):
    for attempt in range(attempts):
        response = requests.request(method, url, timeout=90, **kwargs)
        if response.status_code not in RETRYABLE or attempt == attempts - 1:
            return response
        wait = float(response.headers.get("Retry-After", 0)) or min(30, 2 ** attempt)
        time.sleep(wait + random.uniform(0, 1))

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function callWithRetry(url, options, attempts = 5) {
  for (let attempt = 0; attempt < attempts; attempt++) {
    const response = await fetch(url, options);
    if (!RETRYABLE.has(response.status) || attempt === attempts - 1) return response;
    const wait = Number(response.headers.get("retry-after")) || Math.min(30, 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, (wait + Math.random()) * 1000));
  }
}

Older shapes

Before errors existed, each part of the API had its own error body. They are all still returned, next to errors:

Report a problem

Write to [email protected] and include the X-Request-Id header (or the request_id of the body), the environment, the endpoint and the time. With the request id we can find your request immediately.

Every error code

The catalogue below lists every code the API can answer, its HTTP status, its type and what it means.