Skip to content

Popular

  • Embed not showing on my website
  • Connect Claude or ChatGPT (MCP)
  • Set up a custom domain
  • Order a build through Lumina
  • What Lumina Assistant can do

↑ ↓ to move · Enter to open · Esc to close

Troubleshooting

API and MCP

Authentication failures, permission errors, approvals, rate limits, and MCP connection problems.

Fixes for REST API errors and MCP connection problems. Every API error has the same shape, and the code tells you what went wrong:

json
{
  "error": { "code": "insufficient_scope", "message": "This request requires the api:write token scope." },
  "request_id": "0f5c…"
}

Keep the request_id. Support can find your exact request with it. It is also in the X-Request-Id response header.

401: authentication

CodeCauseFix
unauthorizedNo Authorization header.Send Authorization: Bearer lsk_live_….
invalid_tokenThe header is not Bearer <token>, or the token is wrong, expired, or revoked.Check for a missing Bearer prefix or a cut-off token. Create a new token if it expired.
durable_token_required (MCP)The MCP server only accepts access tokens that start with lsk_live_.Create one on Developers.

Tokens also stop working when the person who created them leaves the agency. Tokens are shown only once. If you lost one, revoke it and create another.

403: permission

CodeCauseFix
insufficient_scopeThe token lacks the scope for this request. Writes need api:write. Blogs need blogs:read, blogs:write, or blogs:generate. api:read does not cover blogs.Create a token with the right permissions. Scopes cannot be added to an existing token.
insufficient_permissionsThe person who created the token does not have this permission in the agency.The owner grants it on Team, or the owner creates the token.
owner_requiredOnly the owner can do this, for example reading billing or team members.Use a token the owner created.
approval_requiredThe action needs the owner's approval, for example a team change, a delete, or opening a client's stored login. details has the approval_id and approve_url.See Approvals.
owner_action_requiredSwitching agency and driving Lumina Assistant are refused for every token. It is also the answer for an action that needs approval when approvals are not switched on yet; the message then says "Approvals are not switched on for this deployment yet".Do it in the dashboard.
token_agency_mismatchYou sent X-Lumina-Agency-Id for a different agency.Remove the header. A token only ever works for its own agency.
feature_unavailableLanders are not switched on for this agency (403), or are switched off for everyone right now (503).For a 403, the owner opts in under Settings → Beta features. A 503 is not something you can change: check the status page or contact support.

Approvals

A token's risky actions wait for the owner. The flow is: call the tool, get approval_required, have the owner approve it on Developers under Approvals (or at the approve_url), check it with lumina_check_approval, then call the same tool again with approval_id and the same arguments. Over the REST API, send the id in the X-Lumina-Approval-Id header. See MCP server.

CodeCauseFix
approval_required (403)A new approval was filed. Nothing ran.Send the owner the approve_url. Once approved, call again with the approval_id.
approval_pending (403)The owner has not decided yet.Ask the owner to open the link or Approvals on Developers.
approval_denied (403)The owner denied it.Do not retry. Ask the owner what they want instead.
approval_consumed (403)That approval already ran its request. Each one runs once.Call again without approval_id to ask for a new one.
approval_expired (403)Approvals last 24 hours.Call again without approval_id to ask again.
approval_mismatch (403)The approval was for a different request: another tool, another id, or different arguments.Send exactly the arguments that were approved, or ask again.
approval_not_found (403)That id was not issued to this token.Use the approval_id this token received, or ask again.
approval_unavailable (503)Approvals could not be checked right now.Try again shortly.

Only the agency owner can approve or deny. Lumina does not email the owner when an approval is filed, so the agent has to pass the link on.

402 and 409: account state

CodeCauseFix
subscription_required (402)The agency has no active plan.Fix billing. See Billing and usage.
setup_requiredAgency setup is not finished.Finish the welcome steps in the dashboard.
slot_confirmation_requiredPublishing would need a paid demo slot. The answer includes the price.Call publishDemo again with the confirmSlots value it gives. From a token, that publish then needs the owner's approval. Or take another demo down.
subdomain_requiredNo subdomain is claimed.Claim one on Brand.
conflictSomething with that value already exists, like an endpoint or email.Use a different value.
core_field_protectedYou tried to change a core onboarding question's type or choices.Hide it instead.
managed_fulfillmentThat project is delivered by Lumina.Use the fulfillment operations instead.
link_unavailableThe portal link cannot be shown.Rotate it first with rotateClientPortalLink.

422: the request was understood but refused

CodeFix
validation_errordetails lists each bad field with its path and a message. Unknown fields are rejected too.
operation_rejectedThe dashboard would have refused this too. The message says why.
invalid_resourceAn id points to something that does not exist or does not belong to this agency.
idempotency_not_supportedIdempotency-Key only works on JSON POST requests. Remove it from other methods.
invalid_originsAn embed domain is not valid. See Embeds.
invalid_bubble_layoutA bubble embed needs a demo with exactly one interactive node.
empty_cart, unknown_serviceA fulfillment cart is empty or names a service that does not exist. Read getFulfillmentCatalog first.

429: rate limits

The API allows 120 requests a minute for each person using a token. The MCP server also allows 120 requests a minute per token. Over the limit you get rate_limited with a Retry-After header in seconds.

  • Wait for Retry-After, then retry.
  • Page through lists with limit (up to 100) instead of fetching one record at a time.
  • Do not retry in a tight loop.

Other request errors

CodeFix
invalid_json (400)The body is empty or not valid JSON.
unsupported_media_type (415)Send Content-Type: application/json.
body_too_large (413)Most bodies are limited to 1 MB, and some operations take less (blog generation takes 16 KB).
method_not_allowed (405)Check the Allow header and the reference.
not_found (404)The id is wrong, or it belongs to another agency.
idempotency_conflict (409)You reused an Idempotency-Key with a different body or path. Use a new key.
request_in_progress (409)The first request with that key is still running, or it failed with a 5xx part way. If it may still be running, wait a minute and retry with the same key: a finished call replays its response. If you got a 5xx back, or the 409 lasts for minutes, read the resource to see whether the change happened and retry with a new key only if it did not.

5xx: our side

internal_error, service_unavailable, auth_unavailable, rate_limit_unavailable, idempotency_unavailable, and other *_unavailable codes mean something on our side failed or is down. Check the status page and wait. auth_unavailable, rate_limit_unavailable and idempotency_unavailable fail before anything runs, so retry those with the same Idempotency-Key. For any other 5xx on a POST, read the resource to see whether the change happened, and if it did not, retry with a new key: the old one stays locked for 24 hours. If it keeps happening, email support with the request_id.

MCP connection problems

SymptomFix
The client says it cannot connect, or shows 405The server takes POST only, with Streamable HTTP transport. Pick HTTP or Streamable HTTP in your client, not SSE or stdio.
401 right awayThe header must be exactly Authorization: Bearer lsk_live_…. Tokens are not accepted in the URL.
batch_not_supportedSend one JSON-RPC message per request.
invalid_modemode is full or compact.
unknown_toolsetThe message lists the valid toolsets. Fix the toolsets value.
The Claude app or ChatGPT app asks you to sign in, then failsThose apps' custom connectors need OAuth sign-in, which the Lumina server does not offer yet. Use Claude Code, Codex, Cursor, Grok Bot, or the OpenAI Responses API.
The agent sees no tools, or too manyUse ?mode=compact for 5 tools that search and call the others, or ?toolsets=clients,demos to load only some.
The agent keeps asking you to approve the same thingIt is changing the arguments between calls, so each call files a new approval. Tell it to call again with the approval_id and exactly the same arguments.
A tool returns binary_responseFile downloads (like a DOCX export) are not returned over MCP. Download them from the REST API.
Changes are refused with insufficient_scopeThe token was created as Read only. Create a Full control token.

Test the connection outside your AI client:

bash
curl -s "https://luminasales.io/api/mcp" \
  -H "Authorization: Bearer YOUR_LUMINA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A list of tools means the server and token are fine, and the problem is in the client's configuration.

Webhooks

The blog webhook (blog.post.ready) is sent once, with a 10-second timeout and no retries. The URL must be public HTTPS. If deliveries fail, the Blogs page shows Last delivery with the error. Make sure your endpoint answers within 10 seconds and verifies the signature as shown in Publish blog posts to your site.

See also: API quickstart, Access tokens, MCP server.

Still stuck? Ask Lumina Assistant in your dashboard (⌘J on any page), or read how to get help.