Errors

The Lightfield API uses conventional HTTP status codes and returns a JSON body for errors. Use the response type and, when present, the machine-readable code to handle errors in your integration.

Error response format

All error responses are wrapped in an error object:

Field	Type	Description
type	string	Machine-readable error type (e.g. bad_request, not_found). Use this to branch on the kind of error.
message	string	Human-readable description of what went wrong.

Example (404):

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "type": "not_found",
    "message": "No resource found in 'accounts' with the given ID."
  }
}

For 400 Bad Request and 422 Unprocessable Content responses, the body can also include:

Field	Type	Description
code	string	Finer-grained code for programmatic handling (see Error codes below). Present on 400 responses.
param	string	Optional. Request location related to the error (e.g. fields.$name, relationships.$owner, Idempotency-Key). Present on 400 and 422 responses.

Example (400):

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "type": "bad_request",
    "message": "Unrecognized field 'bogus' for 'accounts'.",
    "code": "unknown_field",
    "param": "fields.bogus"
  }
}

Example (422):

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": {
    "type": "unprocessable_content",
    "message": "CrmAccount requires name field",
    "param": "fields.name"
  }
}

HTTP status codes

Status	Type	When it happens
400	bad_request	Invalid request (wrong field, relationship, or parameter). Check code and param.
401	unauthorized	Missing or invalid API key. Ensure the request includes Authorization: Bearer YOUR_API_KEY.
403	forbidden	API key is valid but does not have permission for this operation. Check scopes.
404	not_found	The requested resource or entity type does not exist.
409	conflict	Conflict with current state (e.g. duplicate definition, resource locked, concurrent update).
415	unsupported_media_type	Request body is not JSON. Include Content-Type: application/json on POST, PUT, and PATCH requests.
422	unprocessable_content	Request body is valid JSON but business validation failed (e.g. invalid field value). Check param.
429	too_many_requests	Rate limit exceeded. See Rate limits.
500	internal_server_error	Server error. Retry with backoff; contact support if it persists.
503	service_unavailable	The service is temporarily unavailable. Retry with backoff.

Error codes

For 400 Bad Request responses, the code field provides a stable value you can use to handle specific cases:

Code	Meaning
referenced_resource_missing	A field references another resource by ID that does not exist. Use param to see which field (e.g. fields.$company).
relationship_entity_missing	One or more IDs in a relationship (e.g. relationships.$owner) do not exist.
relationship_entity_inactive	One or more IDs in a relationship refer to an inactive (e.g. deleted) entity.
unknown_field	The request included a field that is not defined for this object type. Use param to see the field.
unknown_relationship	The request included a relationship that is not defined for this object type. Use param to see the relationship.
invalid_configuration	Invalid field or relationship configuration.
idempotency_key_too_long	The Idempotency-Key header exceeds the maximum length (255 characters).
invalid_type	A field value has the wrong type (e.g. a string where an object is expected). Use param to see the field.
parameter_missing	A required request parameter is missing. Use param to see which one.
version_header	The Lightfield-Version header is missing or invalid.

Handling errors

• Authentication (401/403) — Verify the API key and that it has the required scopes for the operation.
• Validation (400/422) — Use code and param to identify which field or relationship to fix. For unknown_field or unknown_relationship, ensure you are using the correct object type and field definitions.
• Not found (404) — The resource ID may be wrong, or the resource was deleted. For create/update, ensure any referenced IDs (e.g. in relationships) exist and are active.
• Content type (415) — Ensure the request includes Content-Type: application/json for any request with a body.
• Conflict (409) — Retry the request with fresh data, or use idempotency for create/update to safely retry.
• Rate limit (429) — Honor the Retry-After header and implement exponential backoff. See Rate limits.
• Service unavailable (503) — The server is temporarily overloaded. Retry with exponential backoff.

The official SDKs expose these errors as typed exceptions (e.g. BadRequestError, NotFoundError) with a type and, where applicable, a code and optional param, so you can branch on them in code.