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 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.
`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	The requested state change is not allowed from the current state.
`CLOSED_CASE_LOCKED`	400	The case is closed. Only law-enforcement details may be updated.
`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.
`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.

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