Errors
When a request fails, the API returns a standard JSON error envelope with an appropriate HTTP status code.
Error envelope
Code
| 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
codefield 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. - Retry only
500 INTERNAL_SERVER_ERROR, with backoff. Nothing else is worth a retry:4xxmeans the request is wrong, and500 RECORD_TYPE_MISSINGwill fail identically until the org is reconfigured. Branch oncode, not status.