# Errors

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

Section: Essentials · Last updated: 2026-11-17

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](https://developers.test.transferz.com/guides/get-started/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:

```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

| 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

- `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.

> **To be confirmed by Transferz:** One documented error format for all APIs is still to be confirmed by Transferz. The formats above are
> taken from the current source.

## 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`](https://developers.test.transferz.com/reference/errors/null-value)                                         | A required field is missing or `null`.                        | Send the field.                    |
| [`NOT_NULL_VALUE`](https://developers.test.transferz.com/reference/errors/not-null-value)                                 | A field that must be empty has a value.                       | Leave the field out.               |
| [`BLANK_VALUE`](https://developers.test.transferz.com/reference/errors/blank-value)                                       | A text field is empty or only spaces.                         | Send a value.                      |
| [`INVALID_SIZE`](https://developers.test.transferz.com/reference/errors/invalid-size)                                     | A text or list is too short or too long.                      | Check the limits in the reference. |
| [`INCORRECT_LENGTH_OR_CHARACTERS`](https://developers.test.transferz.com/reference/errors/incorrect-length-or-characters) | A value has the wrong length or characters.                   | Check the format in the reference. |
| [`EMAIL_INVALID`](https://developers.test.transferz.com/reference/errors/email-invalid)                                   | An email address is not valid.                                | Send a valid address.              |
| [`NUMBER_NOT_IN_ALLOWED_RANGE`](https://developers.test.transferz.com/reference/errors/number-not-in-allowed-range)       | A number is too small or too large.                           | Check the range.                   |
| [`DATE_NOT_IN_ALLOWED_RANGE`](https://developers.test.transferz.com/reference/errors/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`](https://developers.test.transferz.com/reference/errors/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`](https://developers.test.transferz.com/reference/errors/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`](https://developers.test.transferz.com/reference/errors/location-not-found)     | `400`  | A location could not be resolved.                                   | Send a more precise address, coordinates or an IATA code.     |
| [`JOURNEY_ERROR`](https://developers.test.transferz.com/reference/errors/journey-error)               | `400`  | The action is not possible for this journey.                        | Read `message`; fetch the journey to check its status.        |
| [`JOURNEY_CHANGE_ERROR`](https://developers.test.transferz.com/reference/errors/journey-change-error) | `400`  | The journey change could not be made.                               | Read `message`; check the change and the journey.             |
| [`JOURNEY_CHANGE_WRONG`](https://developers.test.transferz.com/reference/errors/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`](https://developers.test.transferz.com/reference/errors/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`](https://developers.test.transferz.com/reference/errors/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`](https://developers.test.transferz.com/reference/errors/insufficient-permissions)               | `403`  | Your account lacks the permission for this action. | Check the account; ask Transferz if you need it. |
| [`DELETED_ENTITY_MUTATION_ATTEMPT`](https://developers.test.transferz.com/reference/errors/deleted-entity-mutation-attempt) | `409`  | You tried to change something that was deleted.    | Stop changing it; fetch the current state.       |
| [`API_KEY_LIMIT_REACHED`](https://developers.test.transferz.com/reference/errors/api-key-limit-reached)                     | `403`  | You already have 100 active API keys.              | Delete keys you no longer use.                   |
| [`UNKNOWN`](https://developers.test.transferz.com/reference/errors/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](https://developers.test.transferz.com/support/new) or to your Transferz contact:

- The `X-Request-ID` you sent with the call (see [request IDs](https://developers.test.transferz.com/guides/essentials/conventions#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](https://developers.test.transferz.com/workspace/staging/requests) of your workspace.
