Errors

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

Error envelope

{
	"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 violated 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.
`409 Conflict`	The request conflicts with the current state of a record.
`500 Internal Server Error`	An unexpected error occurred.

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	The requested state change is not allowed from the current state.
`RECORD_TYPE_MISSING`	400	A required record type is not configured.
`CLOSED_CASE_LOCKED`	400	The case is closed; only law-enforcement details may be updated.
`IMMUTABLE_FIELD`	400	A field that cannot be changed after creation was included in an update.
`UNDER_SPECIFIED_SEARCH`	400	A search was submitted without the minimum required filter criteria.
`PLATE_REQUIRED`	400	A license plate is required to persist a vehicle.
`SKU_REQUIRED`	400	A SKU is required to persist an item.
`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.
`DUPLICATE_UUID`	409	A record with the supplied unique identifier already exists.
`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	No transaction ids were supplied to link.
`BATCH_TOO_LARGE`	400	More transactions were supplied than a single 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.

Handling tips

A 401 (rather than an envelope above) means your access token is missing,
expired, or invalid — request a new one. See
Authentication.
Retry only 500 responses, with backoff. 4xx responses indicate a problem
with the request that a retry will not fix.