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 some 400 and 422 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": "A single request may change at most 25 relationships; this one would change 26. Split the change across multiple requests.",
    "code": "relationship_write_limit_exceeded",
    "param": "relationships"
  }
}

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

The code field identifies specific 400 Bad Request and 422 Unprocessable Content errors:

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.
relationship_write_limit_exceeded	The request references more than 25 related records or changes more than 25 links. Split it into smaller requests.
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.
ambiguous_stage_label	A stage label needs a pipeline to resolve it. See pipeline and stage errors.
stage_unresolved_in_pipeline	The supplied stage does not identify one active stage in the selected pipeline.
unknown_pipeline	The supplied pipeline does not resolve to an active pipeline for this object type.

Pipeline and stage errors

Pipeline and stage resolution errors include details inside the error object:

Code	HTTP status	Details and recovery
ambiguous_stage_label	400 for a filter; 422 for a write	candidates lists stage choices with stageOptionId, stageLabel, pipelineId, and pipelineName. Choose an exact stage option ID or specify its pipeline. For non-Opportunity writes, a label requires a pipeline hint even when only one stage matches.
stage_unresolved_in_pipeline	422	pipelineId identifies the selected pipeline; candidates lists possible stages and their owners. Correct the stage or the pipeline hint. An Opportunity label without a hint is resolved within the default opportunity pipeline.
unknown_pipeline	400 for a filter; 422 for a write	activePipelineIds lists available pipelines. Refresh definitions and use a pipeline ID for filtering, or an ID or name for a write hint.

These lists are bounded; truncated: true means more entries exist. Refresh definitions for the full configuration. An empty candidate list can mean the stage label does not exist. Change the input before retrying; do not silently choose the first candidate.

If $pipeline is absent from definitions, a write using it returns 400 unknown_field. Refresh definitions for the target object type and omit fields it does not expose; do not retry the same request.

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.