---
title: Errors | Lightfield
description: Error responses in the Lightfield API.
---

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](#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](/using-the-api/scopes/index.md). |
| 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](/using-the-api/rate-limits/index.md).                                      |
| 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](/using-the-api/scopes/index.md) 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](/objects-in-lightfield/object-types/index.md).
- **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](/using-the-api/idempotency/index.md) for create/update to safely retry.
- **Rate limit (429)** — Honor the `Retry-After` header and implement exponential backoff. See [Rate limits](/using-the-api/rate-limits/index.md).
- **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.