Skip to content

Errors

How the Transferz APIs report errors, and the cause and remedy of each error code.

Updated · 5 min read

The APIs use HTTP status codes and, for most errors, a JSON body with a list of errors. This guide shows the body formats and what to do about each status and code.

Status codes

StatusMeaningWhat to do
200Success.
204Success without a body. Also: a voucher that does not exist (yet).
303See other. Get a voucher returns the voucher's download address in the Location header.Follow the Location header.
400The request is invalid: a missing or wrong field, or an action that is not allowed now.Read errors, fix the request. Do not retry unchanged.
401No valid credentials: the API key is missing, wrong, deleted or expired.See Authentication.
403Your account may not do this, for example for another company's journey.Check the account and the company.
404The journey, booking or other object does not exist, or is not visible to you.Check the id and the environment.
409Conflict: the object was deleted and can no longer change.Fetch the current state before you continue.
5xxSomething went wrong at Transferz.Retry later with increasing waits. If it persists, contact Transferz with the request ID.

Error body

Partners API errors look like this:

JSON
{  "errors": [    {      "code": "UNKNOWN",      "field": "pickupDateTime",      "message": "must not be null"    }  ],  "timestamp": "14-11-2026 03:12:45"}

Transfer Companies API errors have httpStatus instead of field:

JSON
{  "errors": [    {      "httpStatus": "BAD_REQUEST",      "code": "MAX_PAGE_SIZE_LIMIT_EXCEEDED",      "message": "250 exceeds the maximum limit of 100 journeys returned in a single page"    }  ],  "timestamp": "14-11-2026 03:12:45"}

When the error comes from a Transferz service behind the API, you can receive its body unchanged: an errors list whose items have httpStatus, code, message and field.

Fields

FieldTypeMeaning
errorslistOne item per problem found.
errors[].codestringStable error code. Each code in the tables below has its own page. Branch on it.
errors[].messagestringA human-readable explanation. Show or log it; do not parse it, it can change.
errors[].fieldstring or nullThe request field that was rejected. Set on Partners API validation errors, else missing or null.
errors[].httpStatusstringThe HTTP status name, such as BAD_REQUEST. Transfer Companies API and passed-through errors.
timestampstringWhen the error occurred, as dd-MM-yyyy hh:mm:ss.

Responses without a body

  • 401 has an empty body when the X-API-Key header is missing, or the key is unknown, expired or deleted.
  • 404 has an empty body for an id that does not exist (booking, journey, offer, zone or flight). Some endpoints answer 403 with INSUFFICIENT_PERMISSIONS for an unknown id instead.
  • 204 is not an error. Several Transfer Companies actions return it, and so do calls for a voucher or add-ons that are not available yet.

Malformed requests

A request that cannot be read at all, such as invalid JSON or a value of the wrong type, can come back as a standard problem object instead of the format above: type, title, status, detail and instance. Branch on the HTTP status for these.

How to handle errors robustly:

  • Branch on the HTTP status first, then on code. Show or log message; do not parse it.
  • Expect several items in errors, one per invalid field.
  • Expect field to be missing or null.
  • Expect an empty body for some 401 and 404 responses (see above).
  • Do not parse timestamp. Its format is dd-MM-yyyy hh:mm:ss on a 12-hour clock without AM or PM.

Error codes

Validation (Partners API)

These come with 400 and name the invalid field. The Partners API defines the codes below for validation errors, but today most missing or invalid fields are reported with the code UNKNOWN, the field and a short message such as "must not be null". Rely on field and the status, and treat these codes as a bonus when present.

CodeCauseWhat to do
NULL_VALUEA required field is missing or null.Send the field.
NOT_NULL_VALUEA field that must be empty has a value.Leave the field out.
BLANK_VALUEA text field is empty or only spaces.Send a value.
INVALID_SIZEA text or list is too short or too long.Check the limits in the reference.
INCORRECT_LENGTH_OR_CHARACTERSA value has the wrong length or characters.Check the format in the reference.
EMAIL_INVALIDAn email address is not valid.Send a valid address.
NUMBER_NOT_IN_ALLOWED_RANGEA number is too small or too large.Check the range.
DATE_NOT_IN_ALLOWED_RANGEA date is outside the allowed range, for example in the past.Send a later or earlier date.
TIME_NOT_IN_ALLOWED_RANGEA time is outside the allowed range.Send another time.

Partners API

CodeStatusCauseWhat to do
NO_HUB_SELECTED400Neither the origin nor the destination of a quote request is a hub.Make the origin or the destination a hub, such as an airport.
LOCATION_NOT_FOUND400A location could not be resolved.Send a more precise address, coordinates or an IATA code.
JOURNEY_ERROR400The action is not possible for this journey.Read message; fetch the journey to check its status.
JOURNEY_CHANGE_ERROR400The journey change could not be made.Read message; check the change and the journey.
JOURNEY_CHANGE_WRONG400The requested change is not valid.Read message and correct the change.

Transfer Companies API

CodeStatusCauseWhat to do
INVALID_REQUEST400A value is invalid, or the object was not found.Read message and check the ids and values.
MAX_PAGE_SIZE_LIMIT_EXCEEDED400size is larger than the maximum for this search.Use a page size of 100 or less.

All APIs

CodeStatusCauseWhat to do
INSUFFICIENT_PERMISSIONS403Your account lacks the permission for this action.Check the account; ask Transferz if you need it.
DELETED_ENTITY_MUTATION_ATTEMPT409You tried to change something that was deleted.Stop changing it; fetch the current state.
API_KEY_LIMIT_REACHED403You already have 100 active API keys.Delete keys you no longer use.
UNKNOWN500An unexpected error at Transferz.Retry later; if it persists, contact Transferz.

When you contact Transferz

Send these with your question, in a support ticket or to your Transferz contact:

  • The X-Request-ID you sent with the call (see request IDs).
  • The time of the call, and the time zone you read it in.
  • The method, the URL and the status.
  • The response body, including code and message.

Never send your API key. The calls you make with your own staging key are listed, with the request ID you sent, in the request log of your workspace.

Was this helpful?

Back to your build path →