> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intermezzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Find out what went wrong and how to fix it.

When a request fails, the response tells you what went wrong and where. Validation and business errors come back as a list:

```json Response body theme={null}
{
  "errors": [
    {
      "code": "FIELD_UNKNOWN",
      "message": "Unknown field",
      "field": "tax.tax_cde",
      "params": null
    }
  ]
}
```

* `code` is stable. Build your error handling on it, never on `message`.
* `field` is the path to the value. Positions in lists are written as `[n]`, for example `core.phone_numbers[0].phone_type`. An error that is not about one value has `field` `null`.
* `params` holds the values behind the error, for example the existing record's `id` on a duplicate `external_ref`, or the edition on an `If-Match` mismatch. It is `null` when there are none.

A request can fail on several values at once. All of them are returned together.

Authentication errors (`401`, `403`) don't use this list; see [Authentication](https://docs.intermezzo.ai/preview/auth.md#authentication-errors).

## Status codes

| Status | Meaning |
| - | - |
| `400` | A business rule failed, for example a compensation change more than one tax year back |
| `401` | No token sent |
| `403` | Invalid or expired token |
| `404` | The organization, record or referenced record does not exist, or a satellite was never written. Organizations your credentials can't reach also return `404`. |
| `405` | Method not offered, for example `DELETE` on an employee or `POST` on a satellite |
| `409` | Conflict, for example an `external_ref` or payroll ID that is already used, or a change to a closed employee |
| `412` | `If-Match` no longer matches: the satellite changed since you read it (see [Changing data](https://docs.intermezzo.ai/preview/concepts/changing-data.md)) |
| `422` | A value is missing, has the wrong type, or breaks a rule |
| `428` | `If-Match` missing on a `PUT` |

## Common codes

These are the codes you are most likely to see on employee calls. Codes that start with a country code, such as `GB_`, come from that country's rules. The examples in the table come from the UK.

| Code | Status | When |
| - | - | - |
| `FIELD_REQUIRED` | 422 | A required value is missing |
| `FIELD_UNKNOWN` | 422 | A key that is not in the schema: a misspelling, a camelCase name, or a read-only field such as `edition` |
| `FIELD_INVALID_ENUM_VALUE` | 422 | A value not in the allowed list (gender, NI letter, worker type, …) |
| `FIELD_STRING_TOO_SHORT`, `FIELD_STRING_TOO_LONG` | 422 | A length rule is broken (NI number, `rti_id`, `external_ref`, names) |
| `FIELD_STRING_PATTERN_MISMATCH` | 422 | A name contains characters HMRC does not accept |
| `FIELD_VALIDATION_ERROR` | 422 | Other value errors, for example an invalid tax code, email or phone number, or `director_since` missing |
| `VALUE_OUT_OF_RANGE` | 422 | `valid_from` or `valid_at` outside the dates the satellite covers |
| `RANGE_CROSSES_EDITION` | 422 | The `valid_from`–`valid_to` range of a `PUT` crosses an edition boundary |
| `PRECONDITION_MALFORMED` | 422 | `If-Match` is not one quoted edition |
| `EDITION_MISMATCH` | 412 | `If-Match` names an edition other than the one the range lies in |
| `SATELLITE_EXISTS` | 412 | A `PUT` with `If-None-Match: *` for a satellite that already exists |
| `PRECONDITION_REQUIRED` | 428 | A `PUT` without `If-Match` |
| `HUB_DUPLICATE_EXTERNAL_REF` | 409 | The `external_ref` is already used in the organization |
| `HUB_CLOSED` | 409 | A change to a closed employee |
| `GB_RTI_ID_DUPLICATE` | 409 | The payroll ID is already used in the organization |
| `GB_RTI_ID_REUSED_IN_TAX_YEAR` | 422 | The employee used this payroll ID earlier in the tax year |
| `HUB_NOT_FOUND` | 404 | Unknown `employee_id` |
| `SATELLITE_NOT_FOUND` | 404 | A satellite that was never written |
| `WAGE_TYPE_NOT_FOUND` | 404 | Unknown `wage_type_code` in `compensation` |
| `ONE_OR_MORE_PAY_GROUP_NOT_FOUND` | 400 | Unknown `pay_group_id` |
| `COMPENSATION_EFFECTIVE_DATE_TOO_OLD` | 400 | A compensation change more than one tax year back |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.