Self-host & operate

Troubleshooting Lexicor Cloud

Most issues resolve to one of a handful of causes. Every error response carries a detail field that tells you what happened — this page tells you what to do about it.

First checks

Before debugging your integration, rule out a platform issue. Check status.lexicor.io and the unauthenticated health probe:

bash

curl -fsS https://api.lexicor.io/v1/health

If both are green, the problem is almost always the credential, the request, or a plan limit — read on.

No verification email. Check spam, then use Resend verification email on the console /verify page. Your API key stays inactive until the email is verified.
403 “Email verification required before API key is active”. Same cause: verify the email, then retry.
Login says “MFA code required”. Your account has an authenticator app enrolled — supply the current code with your password. If you lost the authenticator, contact support from your account email.

Authentication errors

401 “Missing X-API-Key or Bearer token”. Send your key in the X-API-Key header — not as a query parameter or Authorization header.
403 “Invalid API key”. The key is wrong, or it was rotated — rotation invalidates the old key immediately. Retrieve the current key from the console (Settings) or ask your account admin.
403 “Free trial expired”. The 14-day trial ended. Upgrade with a card in Console → Settings; your data and configuration are preserved.
403 “Insufficient permissions: requires … role”. Key roles are reader < operator < admin. Audit-lake queries and replay require admin; compliance reports require operator or higher.
403 “Feature … not available on … tier”. The endpoint is part of a plan or add-on you don’t have — see Plans & pricing for what each tier includes.

Rate limits and quotas

A 429 always includes a Retry-After header — honor it with exponential backoff.

“Rate limit exceeded (N req/min)”. Per-minute request limit for your tier. Sustained pressure means you need a higher tier.
“Trial mediate quota exceeded”. The trial includes a fixed number of mediate calls; upgrade to continue.
“… soft-cap exceeded (… / month)”. Monthly included-usage cap for Standard/Pro (overage below the cap is billed automatically). Upgrade, or wait for the monthly reset.
“Monthly usage limit reached … set by your account”. A spending cap you configured yourself — raise it in Console → Account.

Mediation, ledger, and lake

Mediate returns 422 with rule details. This is a policy reject, not an error: the problem document lists the rule(s) that failed. Review the policy or the envelope you sent.
Ledger query returns nothing for your correlation id. Confirm you pass the same correlation_id you sent on mediate, and that the mediate call actually returned a decision. If it still fails, contact support with the id and timestamp.
Audit lake returns 503. A platform-side condition — check the status page and retry; report it if it persists.

Console sign-in

Signed out unexpectedly. Cloud sessions last 12 hours; the console returns you to /login when a session expires.
Google/GitHub button missing. Reload; if it stays missing, report it — sign-in providers are configured server-side.

Contacting support

Include these four things

(1) your tenant or organization id — never the API key itself, (2) the UTC timestamp, (3) the request path, and (4) the full error response body. For mediation issues, add the correlation_id. This is usually enough to resolve on the first reply.

Reach us at support@lexicor.io (or the support channel named in your agreement). Contact details, response targets, and security reporting live on the Support page.