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

{
  "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.