ThinkLP
Guides

Errors

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

Error envelope

JSONCode
{ "code": "NOT_FOUND", "message": "No theft case was found for the supplied id." }
FieldDescription
codeMachine-readable error code. Branch on this in your integration.
messageHuman-readable explanation. Intended for logs and diagnostics — do not parse it.

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

HTTP status codes

StatusMeaning
200 OKThe request succeeded.
201 CreatedA record (or link between records) was created.
204 No ContentThe request succeeded with no response body (for example, a detach).
400 Bad RequestThe request was malformed, or it broke a business rule.
403 ForbiddenThe caller lacks access to one or more requested fields (field-level security).
404 Not FoundNo record matches the supplied identifier.
405 Method Not AllowedThe endpoint does not support that HTTP verb.
409 ConflictThe request conflicts with the current state of a record.
422 Unprocessable EntityA key or value in the request cannot be used, such as an Incident Type the org does not map.
500 Internal Server ErrorAn unexpected error occurred, or the org is misconfigured.

Error codes

CodeTypical statusWhen it occurs
BAD_REQUEST400The request body or parameters are invalid or missing.
INVARIANT_VIOLATION400The request would break a domain rule.
INVALID_TRANSITION400Reserved. No route returns it.
IMMUTABLE_FIELD400An update changed a field that is fixed after creation. Resending its current value is fine.
UNDER_SPECIFIED_SEARCH400The search did not carry the minimum required filter criteria.
PLATE_REQUIRED400A vehicle needs a license plate before the API can save it.
SKU_REQUIRED400An item needs a SKU before the API can save it.
TOO_MANY_MATCHES400A search matched more records than the endpoint will return. Refine it.
FLS_DENIED403The caller cannot access one or more requested fields (field-level security).
NOT_FOUND404No record matches the supplied identifier.
METHOD_NOT_ALLOWED405The endpoint does not support that verb.
DUPLICATE_UUID409A record with the supplied uuid already exists.
INCIDENT_TYPE_NOT_MAPPED422The 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_MISSING500A required record type is not configured in the org — a configuration problem, not a request problem.
INTERNAL_SERVER_ERROR500An 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:

CodeTypical statusWhen it occurs
INVALID_CASE_PAYLOAD400The case details embedded in a create-from-transactions request are invalid.
EMPTY_TRANSACTION_SET400The request named no transaction ids to link.
BATCH_TOO_LARGE400The request named more transactions than one request allows.
REFERENCE_NOT_FOUND404A referenced record (transaction or related record) does not exist.
ALREADY_LINKED409One or more of the supplied transactions are already linked to a case.
MISCONFIGURED500Required 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.

CodeTypical statusWhen it occurs
CUSTOM_PROPERTY_NOT_DEFINED422The request sent a key that is not a custom property on the case.
CUSTOM_PROPERTY_REQUIRED422The request omitted a required custom property, or sent it blank.
CUSTOM_PROPERTY_NOT_WRITABLE422A 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: 4xx means the request is wrong, and 500 RECORD_TYPE_MISSING will fail identically until the org is reconfigured. Branch on code, not status.
Last modified on