Errors
How the Transferz APIs report errors, and the cause and remedy of each error code.
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
| Status | Meaning | What to do |
|---|---|---|
200 | Success. | |
204 | Success without a body. Also: a voucher that does not exist (yet). | |
303 | See other. Get a voucher returns the voucher's download address in the Location header. | Follow the Location header. |
400 | The 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. |
401 | No valid credentials: the API key is missing, wrong, deleted or expired. | See Authentication. |
403 | Your account may not do this, for example for another company's journey. | Check the account and the company. |
404 | The journey, booking or other object does not exist, or is not visible to you. | Check the id and the environment. |
409 | Conflict: the object was deleted and can no longer change. | Fetch the current state before you continue. |
5xx | Something 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:
{ "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:
{ "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
| Field | Type | Meaning |
|---|---|---|
errors | list | One item per problem found. |
errors[].code | string | Stable error code. Each code in the tables below has its own page. Branch on it. |
errors[].message | string | A human-readable explanation. Show or log it; do not parse it, it can change. |
errors[].field | string or null | The request field that was rejected. Set on Partners API validation errors, else missing or null. |
errors[].httpStatus | string | The HTTP status name, such as BAD_REQUEST. Transfer Companies API and passed-through errors. |
timestamp | string | When the error occurred, as dd-MM-yyyy hh:mm:ss. |
Responses without a body
401has an empty body when theX-API-Keyheader is missing, or the key is unknown, expired or deleted.404has an empty body for an id that does not exist (booking, journey, offer, zone or flight). Some endpoints answer403withINSUFFICIENT_PERMISSIONSfor an unknown id instead.204is 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 logmessage; do not parse it. - Expect several items in
errors, one per invalid field. - Expect
fieldto be missing ornull. - Expect an empty body for some
401and404responses (see above). - Do not parse
timestamp. Its format isdd-MM-yyyy hh:mm:sson 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.
| Code | Cause | What to do |
|---|---|---|
NULL_VALUE | A required field is missing or null. | Send the field. |
NOT_NULL_VALUE | A field that must be empty has a value. | Leave the field out. |
BLANK_VALUE | A text field is empty or only spaces. | Send a value. |
INVALID_SIZE | A text or list is too short or too long. | Check the limits in the reference. |
INCORRECT_LENGTH_OR_CHARACTERS | A value has the wrong length or characters. | Check the format in the reference. |
EMAIL_INVALID | An email address is not valid. | Send a valid address. |
NUMBER_NOT_IN_ALLOWED_RANGE | A number is too small or too large. | Check the range. |
DATE_NOT_IN_ALLOWED_RANGE | A date is outside the allowed range, for example in the past. | Send a later or earlier date. |
TIME_NOT_IN_ALLOWED_RANGE | A time is outside the allowed range. | Send another time. |
Partners API
| Code | Status | Cause | What to do |
|---|---|---|---|
NO_HUB_SELECTED | 400 | Neither 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_FOUND | 400 | A location could not be resolved. | Send a more precise address, coordinates or an IATA code. |
JOURNEY_ERROR | 400 | The action is not possible for this journey. | Read message; fetch the journey to check its status. |
JOURNEY_CHANGE_ERROR | 400 | The journey change could not be made. | Read message; check the change and the journey. |
JOURNEY_CHANGE_WRONG | 400 | The requested change is not valid. | Read message and correct the change. |
Transfer Companies API
| Code | Status | Cause | What to do |
|---|---|---|---|
INVALID_REQUEST | 400 | A value is invalid, or the object was not found. | Read message and check the ids and values. |
MAX_PAGE_SIZE_LIMIT_EXCEEDED | 400 | size is larger than the maximum for this search. | Use a page size of 100 or less. |
All APIs
| Code | Status | Cause | What to do |
|---|---|---|---|
INSUFFICIENT_PERMISSIONS | 403 | Your account lacks the permission for this action. | Check the account; ask Transferz if you need it. |
DELETED_ENTITY_MUTATION_ATTEMPT | 409 | You tried to change something that was deleted. | Stop changing it; fetch the current state. |
API_KEY_LIMIT_REACHED | 403 | You already have 100 active API keys. | Delete keys you no longer use. |
UNKNOWN | 500 | An 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-IDyou 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
codeandmessage.
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.