# Errors

When a request fails, the API returns a standard JSON error envelope with an
appropriate HTTP status code.

## Error envelope

```json
{
	"code": "NOT_FOUND",
	"message": "No theft case was found for the supplied id."
}
```

| Field     | Description                                                                      |
| --------- | -------------------------------------------------------------------------------- |
| `code`    | Machine-readable error code. Branch on this in your integration.                 |
| `message` | Human-readable explanation. Intended for logs and diagnostics — do not parse it. |

Always drive programmatic handling off `code`. Treat `message` as informational.

## HTTP status codes

| Status                      | Meaning                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `200 OK`                    | The request succeeded.                                                                       |
| `201 Created`               | A record (or link between records) was created.                                              |
| `204 No Content`            | The request succeeded with no response body (for example, a detach).                         |
| `400 Bad Request`           | The request was malformed, or it broke a business rule.                                      |
| `403 Forbidden`             | The caller lacks access to one or more requested fields (field-level security).              |
| `404 Not Found`             | No record matches the supplied identifier.                                                   |
| `405 Method Not Allowed`    | The endpoint does not support that HTTP verb.                                                |
| `409 Conflict`              | The request conflicts with the current state of a record.                                    |
| `422 Unprocessable Entity`  | A key or value in the request cannot be used, such as an Incident Type the org does not map. |
| `500 Internal Server Error` | An unexpected error occurred, or the org is misconfigured.                                   |

## Error codes

| Code                       | Typical status | When it occurs                                                                                                                                                                |
| -------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BAD_REQUEST`              | 400            | The request body or parameters are invalid or missing.                                                                                                                        |
| `INVARIANT_VIOLATION`      | 400            | The request would break a domain rule.                                                                                                                                        |
| `INVALID_TRANSITION`       | 400            | Reserved. No route returns it.                                                                                                                                                |
| `IMMUTABLE_FIELD`          | 400            | An update changed a field that is fixed after creation. Resending its current value is fine.                                                                                  |
| `UNDER_SPECIFIED_SEARCH`   | 400            | The search did not carry the minimum required filter criteria.                                                                                                                |
| `PLATE_REQUIRED`           | 400            | A vehicle needs a license plate before the API can save it.                                                                                                                   |
| `SKU_REQUIRED`             | 400            | An item needs a SKU before the API can save it.                                                                                                                               |
| `TOO_MANY_MATCHES`         | 400            | A search matched more records than the endpoint will return. Refine it.                                                                                                       |
| `FLS_DENIED`               | 403            | The caller cannot access one or more requested fields (field-level security).                                                                                                 |
| `NOT_FOUND`                | 404            | No record matches the supplied identifier.                                                                                                                                    |
| `METHOD_NOT_ALLOWED`       | 405            | The endpoint does not support that verb.                                                                                                                                      |
| `DUPLICATE_UUID`           | 409            | A record with the supplied `uuid` already exists.                                                                                                                             |
| `INCIDENT_TYPE_NOT_MAPPED` | 422            | The org's Incident Type picklist does not list the value sent. The body names `incidentTypeKey` as the `field`. Map the Incident Type to a listed value; nothing was written. |
| `RECORD_TYPE_MISSING`      | 500            | A required record type is not configured in the org — a configuration problem, not a request problem.                                                                         |
| `INTERNAL_SERVER_ERROR`    | 500            | An unexpected server error occurred.                                                                                                                                          |

> The status shown is the usual pairing. Always read the HTTP status **and** the
> `code` field together, since a single status can carry more than one code.

## Insights (case linkage) codes

The `/insights/…` endpoints reuse `BAD_REQUEST`, `FLS_DENIED`, `NOT_FOUND`, and
`INTERNAL_SERVER_ERROR` above, and add these:

| Code                    | Typical status | When it occurs                                                                  |
| ----------------------- | -------------- | ------------------------------------------------------------------------------- |
| `INVALID_CASE_PAYLOAD`  | 400            | The case details embedded in a create-from-transactions request are invalid.    |
| `EMPTY_TRANSACTION_SET` | 400            | The request named no transaction ids to link.                                   |
| `BATCH_TOO_LARGE`       | 400            | The request named more transactions than one request allows.                    |
| `REFERENCE_NOT_FOUND`   | 404            | A referenced record (transaction or related record) does not exist.             |
| `ALREADY_LINKED`        | 409            | One or more of the supplied transactions are already linked to a case.          |
| `MISCONFIGURED`         | 500            | Required Insights configuration (permission set or custom metadata) is missing. |

## Custom property codes

`POST /theft-cases` can refuse a `customProperties` entry with one of these.
Each body names the key in `field` and never includes the value, and nothing is
written.

| Code                           | Typical status | When it occurs                                                                                                                       |
| ------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `CUSTOM_PROPERTY_NOT_DEFINED`  | 422            | The request sent a key that is not a custom property on the case.                                                                    |
| `CUSTOM_PROPERTY_REQUIRED`     | 422            | The request omitted a required custom property, or sent it blank.                                                                    |
| `CUSTOM_PROPERTY_NOT_WRITABLE` | 422            | A custom property value is not a string or does not convert, the caller cannot create its field, or the database rejected the write. |

A caller without create access to a custom property's field gets
`422 CUSTOM_PROPERTY_NOT_WRITABLE` with the key in `field`, never the field API
name. A standard field the caller cannot create still answers `403 FLS_DENIED`.

## Handling tips

- A `401` (rather than an envelope above) means your access token is missing,
  expired, or invalid — request a new one. See
  [Authentication](./authentication.md).
- Retry only `500 INTERNAL_SERVER_ERROR`, with backoff. Nothing else is worth a
  retry: `4xx` means the request is wrong, and `500 RECORD_TYPE_MISSING` will
  fail identically until the org is reconfigured. Branch on `code`, not status.
