Errors & troubleshooting

Response envelope

All responses share the same shape:

{
  "success": true,
  "data": { ... },
  "message": "..."
}

{
  "success": false,
  "message": "Human-readable summary",
  "data": null,
  "error": "Optional detail or array of field errors"
}

Check success, not just the HTTP status. message is safe to surface to users; error is for logs and debugging.

Status codes

Ingestion and auth endpoints return 400 for validation failures, not 422. The recommendation service is the exception: it returns 422 when a strategy is missing its required input (see Personalisation).

400 Bad Request

Missing field, wrong type, or schema mismatch. Validation errors include a per-field error array:

{
  "success": false,
  "message": "Validation Failed",
  "error": [
    { "path": "email", "message": "Invalid email" },
    { "path": "password", "message": "String must contain at least 8 character(s)" }
  ]
}

401 Unauthorized

Credentials are missing, invalid, or expired. Never retry a 401 with the same credentials.

403 Forbidden

The credential is valid but lacks permission for this resource or action.

404 Not Found

The resource doesn't exist, or it belongs to a different organization. lehnz does not leak existence: a 404 looks the same whether the ID is invalid or belongs to another tenant.

429 Too Many Requests

You hit a rate limit. Responses include RateLimit-* headers (draft-7) for computing the right backoff.

See Retries & rate limits for backoff strategies.

500 Internal Server Error

An unexpected server-side failure. Internal details are scrubbed before reaching the client.

{
  "success": false,
  "message": "An unexpected error occurred",
  "data": null,
  "error": null
}

500s are exceptional. Retry once with a short delay, then escalate. If you see them in volume, contact support with timestamps and any request IDs from your client logs.

A defensive client

Branch on success, log the error field, surface message to the user, and only retry 429 or 500.

async function callLehnz(url: string, init?: RequestInit) {
  const res = await fetch(url, init);
  const body = await res.json();

  if (body.success) return body.data;

  console.error('lehnz error', { status: res.status, body });

  if (res.status === 429 || res.status >= 500) {
    throw new RetryableError(body.message);
  }
  throw new TerminalError(body.message);
}

Common issues

Recommendations look generic or stale. Users with fewer than ~10 behavioral events get popularity-based fallback results. Quality improves as events accumulate. If you recently uploaded catalog items, allow a few minutes for async processing. Also check that items have status: "active" and that anonymous and authenticated sessions are stitched (see Identity stitching).

Events not showing in the dashboard. A 202 Accepted means events are queued; they typically appear within seconds. If they never arrive, open the Network tab and check for failed POSTs to api.lehnz.com. Common causes: ad-blockers, a strict CSP, or the request being cancelled on page navigation (add keepalive: true). Browser-side calls require a publishable key (lehnz_pk_); secret keys return 403.

"Invalid API Key" but the key looks right. Hidden whitespace from password managers can cause this: trim the value before sending. Also confirm the key hasn't been revoked in the dashboard, that you're sending it as X-API-KEY with no Bearer prefix, and that you haven't swapped a staging key into production (or vice versa).

CORS errors in the browser. lehnz allows browser-origin calls to ingestion and recommendations endpoints with publishable (lehnz_pk_) keys. If you're seeing CORS failures: confirm you're using the publishable key (not the secret one) and that the URL is https://. Many reported CORS errors are actually auth failures misreported by the browser; inspect the Network tab for the real response body.

CSV upload rejected. The first row must be column names. Save the file as UTF-8 (Latin-1 and other encodings produce malformed-CSV errors). Wrap fields containing commas in double quotes: "red, large". Avoid smart quotes from word processors; use a plain text editor or a database export tool.

Still stuck? Contact support@lehnz.com with your organization slug, the request URL, the request payload (with secrets redacted), and the full response body. Including the timestamp helps correlate against server logs.