Errors and limits

REST errors use a stable JSON envelope.

{
  "ok": false,
  "error": "agent_scope_missing",
  "message": "This API key does not have the replies:write scope.",
  "requestId": "req_example"
}

The response also includes x-request-id. Share that identifier with Loresta support instead of sending secrets or private message bodies.

HTTP status guide

Status	Meaning	Caller action
`400`	Invalid JSON, fields, or idempotency key	Fix the request before retrying
`401`	Missing, invalid, expired, or revoked key	Replace or rotate the credential
`403`	Inactive workspace, missing scope, or rejected browser origin	Correct access or origin configuration
`404`	Profile or conversation is outside the key’s workspace or unavailable	Verify the tenant-scoped identifier
`409`	Confirmation required or idempotency conflict	Resolve the named state before retrying
`413`	Request body is too large	Reduce the payload
`415`	JSON content type is missing	Send `Content-Type: application/json`
`429`	Per-minute rate limit or monthly reply allowance reached	Back off or wait for allowance renewal
`500`	Unexpected internal failure	Retry with backoff and retain `x-request-id`
`503`	Agent API or required configuration is unavailable	Stop and retry later

Common error codes

Code	Meaning
`agent_auth_required`	Authorization header is missing or malformed
`agent_key_invalid`	Key is unknown, expired, or revoked
`agent_workspace_inactive`	Workspace is not active on a paid plan
`agent_scope_missing`	Key does not include the route or tool scope
`agent_origin_rejected`	Browser origin is not configured
`agent_profile_not_found`	Profile is unavailable inside the key’s workspace
`agent_conversation_not_found`	Conversation is unavailable inside the key’s workspace
`agent_confirmation_required`	Handoff was called without `confirm: true`
`idempotency_key_required`	Write request is missing a valid key
`idempotency_key_reused`	The key was reused with different input
`idempotency_in_progress`	An identical request is still processing
`agent_monthly_quota_used`	Shared monthly reply allowance is exhausted
`rate_limited`	A per-minute authentication, key, or address limit was exceeded

Rate limits and quotas

Authenticated key limits are plan-aware and currently enforce 60, 180, or 600 requests per minute. Invalid authentication attempts are separately limited before key lookup. Loresta does not currently return remaining-request headers, so clients should not estimate capacity from request counts.

Draft usage shares the workspace’s monthly reply allowance with connected inboxes and creator Page replies. GET /api/v1/agent/usage returns the current limit, used count, remaining count, and usage period.

Idempotency

draft and handoff require an Idempotency-Key containing 8 to 120 safe characters. Repeating the same operation, key, and input returns the stored response with idempotency-replayed: true. Reusing the key with different input returns HTTP 409.

Use a unique key per logical write. Preserve it across network retries, but generate a new key when the intended input changes.

Retry policy

Do not retry validation, scope, tenant, or confirmation errors without changing the request.
Retry 429, 500, and 503 with capped exponential backoff and jitter.
Preserve the idempotency key for a retry of the same write.
Stop retrying when the operation returns idempotency_in_progress; wait before polling or retrying.