Troubleshooting

Start with the structured error code and x-request-id. Keep the identifier, HTTP status, route, and approximate timestamp. Do not send Loresta an API key, provider token, or private message body.

Agent API

The request returns 401

Confirm the header uses Authorization: Bearer ..., then check whether the key expired or was revoked. Rotate it in Developer settings if the raw secret is no longer available.

The request returns agent_scope_missing

Create or rotate a key with the required scope. Do not reuse a broad key merely to bypass scope planning.

The profile returns 404

The profileId must identify an active creator profile in the same workspace as the key. The public v1 API does not list profiles and intentionally does not reveal cross-workspace ownership.

A write returns an idempotency conflict

Reuse a key only for the identical logical request. Generate a new key when the input changes. When the error is idempotency_in_progress, wait before retrying the same request.

Drafting returns 429

Check GET /api/v1/agent/usage. The response distinguishes the shared monthly reply allowance from operation totals. A rate_limited error is a per-minute boundary, while agent_monthly_quota_used is the workspace allowance.

MCP

Initialization fails

Send JSON-RPC 2.0 to POST /mcp, include JSON content type, allow application/json or text/event-stream, and use one of the documented protocol versions.

A tool is missing

tools/list hides tools whose scope is not present on the key. Rotate or create a correctly scoped key.

A tool response has isError: true

Read structuredContent.error and structuredContent.message. Tool policy errors are returned inside the JSON-RPC result even when the HTTP exchange succeeds.

Social inboxes

• Reconnect when a connection shows that state or provider token refresh fails.
• Confirm the provider returned the DM or publishing capability you need.
• Use the Loresta dashboard connection flow rather than calling private callback routes.
• Disconnect and reinstall when the provider account or application permissions changed materially.

Discord

Review the Discord troubleshooting checklist for channel permissions, role hierarchy, support cards, and interaction signatures.

Local development

• Apply local migrations with npm run db:local.
• Use npm run dev:pages for the Cloudflare Pages runtime, not only the static Astro dev server, when testing Functions.
• Confirm required feature flags and provider variables exist in the local environment.
• Run the focused QA command before broad release checks.

If the failure remains, contact Loresta support with x-request-id, timestamp, route, status, and non-sensitive reproduction steps.