> ## Documentation Index
> Fetch the complete documentation index at: https://api.lensmor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error conventions

> Understand Lensmor API error responses, status codes, trace fields, retry behavior, and client handling patterns for production integrations.

Lensmor API errors use real HTTP status codes.

## Error body

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": 401,
  "message": "Invalid API key",
  "errorKey": "INVALID_API_KEY",
  "traceId": "2be6d7f4-3b2d-4d11-8e2d-7a2e4c3e9a10"
}
```

## Common status codes

| Status                  | Meaning                                                                     | Recommended client behavior                                |
| ----------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `400 Bad Request`       | Invalid input or unsupported request shape.                                 | Validate user input and fix the request before retrying.   |
| `401 Unauthorized`      | Missing, malformed, revoked, or invalid API key.                            | Ask the user to reconnect or rotate the key.               |
| `402 Payment Required`  | Insufficient credits or access for a credit-consuming operation.            | Stop automatic retries and surface the credit requirement. |
| `404 Not Found`         | Requested resource does not exist or is not visible to the caller.          | Re-check stored identifiers; do not retry indefinitely.    |
| `409 Conflict`          | Business conflict, profile state conflict, or task/workflow state conflict. | Refresh state before retrying.                             |
| `429 Too Many Requests` | Rate limit exceeded.                                                        | Retry only after `Retry-After`; use exponential backoff.   |

## Trace fields

Error responses include `traceId` for troubleshooting. The same value is also returned in the `X-Request-ID` response header when available.

When contacting support, include:

* endpoint path and method
* response status
* `traceId`
* approximate request time
* non-sensitive identifiers such as `event_id`, `exhibitor_id`, `personnel_id`, or `taskId`

Do not include API keys or unlocked email addresses in support logs.

## Retry guidance

* Retry network failures and `429` responses with backoff.
* Do not automatically retry `400` or `401` without changing the request.
* Treat `402` as a product state, not a transient failure.
* For asynchronous contact unlocks, retry polling the task endpoint rather than creating duplicate unlock tasks.

## Notes

* Error bodies do not include raw debugging fields.
* Individual endpoint pages may list the subset of statuses most relevant to that route.