Error catalog
Exact Octopus Prime error texts by component: plugin setup and runtime, close codes, service errors, delivery failure reasons and app messages, with fixes.
Shows only the sections, questions and table rows that contain the text. Esc clears it.
Exact texts are copied verbatim (placeholders in angle brackets or braces). Search this page for a distinctive fragment of the message you see. Machine-readable version: /ai/errors.json. Symptom-first guidance: /ai/troubleshooting.
Service errors have no numeric codes: every HTTP error body is {"detail": "<text>"} (validation errors with status 422 may be a list of field errors). Plugin errors appear in the output of openclaw channels add, in the Gateway log (openclaw channels logs --channel octopus-prime, openclaw logs --follow; lines start with octopus-prime) or in the error field of openclaw channels status --probe --channel octopus-prime --json.
Plugin setup errors
Printed by openclaw channels add --channel octopus-prime …. When setup fails, nothing is written to the OpenClaw config.
| Exact text | Where | Cause | Fix | Verify |
|---|---|---|---|---|
Octopus Prime setup code is required |
Output of openclaw channels add --channel octopus-prime | The command ran without --setup-code. | Create a code in the web app (OpenClaw Agents → Connect OpenClaw, or New setup code) and run openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <code> | The command finishes without error and the connector leaves SETUP REQUIRED. |
Octopus Prime AI bootstrap failed (<HTTP status>): <server body> |
Output of openclaw channels add; <server body> is the service's JSON, for example {"detail":"Invalid or used setup code"} | The setup-code exchange (POST /api/connector/bootstrap) was refused. Read the detail: 404 Invalid or used setup code, 410 Setup code expired, 404 Connector not found, 404 Connector revoked, 409 Organization is archived, 426 Unsupported OpenClaw plugin API <v>. Supported: ['2026.9.7']. | Fix by detail (see the service errors for the bootstrap endpoint): new code for used/expired codes; Connect OpenClaw again for a missing or revoked connector; an Owner restores an archived organization; install the plugin package Octopus Prime provides for 426. | Rerun succeeds; the connector moves from SETUP REQUIRED to CONNECTING. |
Octopus Prime AI bootstrap returned an incomplete connector credential |
Output of openclaw channels add | The exchange answered successfully but without the credential or identifiers (service or proxy problem). Nothing was written. | Retry with a new setup code after a few minutes; check that no proxy rewrites HTTPS responses; if it repeats, contact support with openclaw triage --non-interactive output. | Rerun succeeds. |
Octopus Prime requires a valid authenticated connector identity |
Output of openclaw channels add | The exchange returned an invalid connector id. | Same as the incomplete-credential case: retry with a new code; contact support if it repeats. | Rerun succeeds. |
Octopus Prime requires a valid authenticated organization identity |
Output of openclaw channels add | The exchange returned an invalid organization id. | Retry with a new code; contact support if it repeats. | Rerun succeeds. |
Octopus Prime AI bootstrap backend identity does not match the requested canonical backend |
Output of openclaw channels add | The backend that answered is not the one named in --backend-url (wrong URL, or a redirect or proxy in between). | Use exactly --backend-url 'https://api.octopusprimeai.com' and make sure nothing redirects it. | Rerun succeeds. |
Invalid ingress origin URL |
Output of openclaw channels add | --backend-url is not a valid URL. | Use exactly 'https://api.octopusprimeai.com'. | Rerun succeeds. |
Ingress origin requires a secure HTTPS URL without credentials, query or fragment |
Output of openclaw channels add | --backend-url is not https:// or contains user:password@, ?query or #fragment. | Use exactly 'https://api.octopusprimeai.com'. | Rerun succeeds. |
Octopus Prime supports the default connector account only |
Output of openclaw channels add | --account was given with a value other than the default account. | Remove --account. One Gateway (OpenClaw profile) connects to one organization; use a separate profile or Gateway for another organization. | Rerun succeeds. |
Octopus Prime setup must complete authenticated connector exchange before configuration is written |
Output of openclaw channels add | Setup was asked to write config without a successful code exchange (for example only --connector-token, --connector-id or --org-id were passed). | Run setup with --setup-code: openclaw channels add --channel octopus-prime --backend-url 'https://api.octopusprimeai.com' --setup-code <code> | Rerun succeeds; channels.octopus-prime is written. |
DNS, TLS or timeout error during setup (text comes from the operating system or runtime) |
Output of openclaw channels add | The Gateway host cannot reach https://api.octopusprimeai.com (no outbound HTTPS, DNS, firewall or proxy problem). | Fix outbound HTTPS from the Gateway host, then rerun setup (with a new code if 15 minutes have passed). | curl -sS https://api.octopusprimeai.com/api/health/live prints {"status":"live"}. |
Plugin runtime errors
Gateway log lines, rejection reasons and channels status errors while the plugin runs.
| Exact text | Where | Cause | Fix | Verify |
|---|---|---|---|---|
octopus-prime connector socket closed (code <N>); reconnecting in <n> seconds |
Gateway log (warning); openclaw channels logs --channel octopus-prime | The connection to the service closed with close code N; n is the backoff (2, 4, 8, then 15 s). | Look up N under Connection close codes (4401, 4403, 4426, 1002, 1001, 1011, 1012). Occasional 1006 or 1012 lines are normal; a repeating code is not. | The line stops repeating and the connector shows READY. |
octopus-prime connector socket was silent for 50 seconds; reconnecting in <n> seconds |
Gateway log | No frame arrived for 50 s (network drop, sleeping host, or a proxy that kills idle or long-lived WebSockets). | Usually recovers by itself. If it repeats, check outbound WSS stability, proxy idle timeouts and host sleep settings. | No new lines; connector READY. |
octopus-prime connector socket could not be created; reconnecting in <n> seconds |
Gateway log | The WebSocket could not be opened (bad backendUrl or no network). | Check channels.octopus-prime.backendUrl is https://api.octopusprimeai.com and outbound WSS is allowed. | Connector READY. |
<issue>. Run Octopus Prime setup, then restart this channel account. |
error field of openclaw channels status (account inspect); issue is one of: Octopus Prime requires a resolved connector credential · Octopus Prime requires a canonical HTTPS backend URL · Octopus Prime requires a valid connector identity pin · Octopus Prime requires a valid organization identity pin | channels.octopus-prime is missing or invalid: no connectorToken (or a SecretRef that does not resolve), a non-canonical backendUrl, or invalid connectorId/orgId. | Create a new setup code and rerun setup. For a SecretRef credential, fix the secret source and run openclaw secrets reload. | tokenStatus: "available" and statusState: "ready" in openclaw channels status --probe --channel octopus-prime --json. |
Connector pin changed; restart the Octopus Prime channel account to activate the new identity generation |
openclaw channels status (statusState restart-required) | connectorId or orgId changed while the account was running (after setup with a code for a different connector). | openclaw gateway restart (add --safe to wait for active work). | statusState: "ready"; connector READY. |
Authenticated connector does not match the configured connector identity pin |
openclaw channels status (statusState error; transport stopped) | The credential belongs to a different connector than connectorId, usually because config from two setups was mixed or copied. | Create a new setup code for the intended connector and rerun setup; do not hand-edit connectorId, orgId or connectorToken. | statusState: "ready". |
Authenticated connector changed within an active ingress generation |
Gateway log or channels status | Config identity changed under a running connection. | Restart after config changes: openclaw gateway restart. | Connector READY. |
Current configuration does not match the authenticated ingress origin |
Gateway log or channels status | backendUrl or ids were edited while the connection was running. | openclaw gateway restart; prefer rerunning setup over hand edits. | Connector READY. |
Current configuration no longer matches the authenticated outbound origin |
Gateway log or channels status | Config was edited while replies were being sent. | openclaw gateway restart. | Connector READY. |
Connector outbound readiness generation is no longer current |
Gateway log or channels status | The connection restarted while a reply was pending. | Usually transient; if it persists, openclaw gateway restart. | Replies arrive. |
Backend did not return the exact negotiated connector contract |
Gateway log (octopus-prime inbound error: …); the plugin closes the connection with 1002 protocol-error | Protocol mismatch between plugin and service, or a proxy altering WebSocket traffic. | Install the plugin package Octopus Prime currently provides; bypass WebSocket-inspecting proxies; contact support if it persists. | Reconnect succeeds; connector READY. |
Protocol welcome is not an object |
Gateway log (octopus-prime inbound error: …); closes 1002 | Unexpected frame from the service or a proxy. | As above. | Reconnect succeeds. |
Backend sent application data before protocol negotiation completed |
Gateway log (octopus-prime inbound error: …); closes 1002 | Protocol order violated (version mismatch or proxy). | As above. | Reconnect succeeds. |
Connector frame is not an object |
Gateway log (octopus-prime inbound error: …); closes 1002 (invalid JSON closes 1002 invalid-json) | Malformed frame. | As above. | Reconnect succeeds. |
Agent is not currently announced by this connector |
Sent by the plugin as a rejection reason; the message's chip becomes FAILED (last_error connector_rejected) | Octopus Prime targeted an agent id that this Gateway no longer has (agent removed or renamed id in OpenClaw). | Restore the agent in OpenClaw (openclaw agents list) or message an agent that exists. New messages deliver once the agent is announced again. | A new message reaches RESPONDED. |
Inbound message is missing stable event, channel, agent, sender, or body facts |
Plugin rejection reason; chip FAILED | Malformed delivery from the service. | Contact support with the time and conversation; include openclaw triage --non-interactive output. | — |
Inbound thread id is invalid |
Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
Inbound sender name is invalid |
Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
Inbound timestamp is invalid |
Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
Inbound frame is not an object |
Plugin rejection reason; chip FAILED | Malformed delivery. | Contact support. | — |
Octopus target agent is not currently configured |
Dispatch error in the Gateway log | The delivery names an agent id that is not in the Gateway's agent list. | Add or restore the agent in OpenClaw (openclaw agents list), or use another agent in Octopus Prime. | A new message reaches RESPONDED. |
Octopus connector account is disabled |
Dispatch error | channels.octopus-prime.enabled is false. | openclaw plugins enable octopus-prime and/or set channels.octopus-prime.enabled back to true. | Connector READY. |
Octopus connector account is unavailable |
Dispatch error | A non-default OpenClaw account was addressed. | Use only the default account; remove any accounts config for octopus-prime. | Connector READY. |
OpenClaw did not dispatch admitted Octopus event <event_id> |
Gateway log | OpenClaw core declined to run the agent turn (agent configuration, model or provider error). | Read openclaw logs --follow around that time; fix the agent or model configuration; ask the person to send the message again. | Chip goes WORKING then RESPONDED. |
octopus-prime Working status could not be sent |
Gateway log | The connection dropped during a turn. | Transient; check connectivity if frequent. | — |
octopus-prime outbound delivery failed: <error> |
Gateway log | Sending a reply failed; OpenClaw core retries it (on 2026.9.8 up to 5 attempts, 5 s to 10 min apart). | Read the inner <error> (entries below). | The reply appears; chip RESPONDED. |
Timed out waiting for backend send receipt |
Inner error of octopus-prime outbound delivery failed | No receipt within 20 s. Includes the case where the agent was removed from the conversation or the conversation was archived (the service ignores the reply). | Check the agent is still in the conversation and the conversation is active; otherwise check the connection. | Next reply appears. |
Timed out waiting for backend status receipt |
Inner error | Same as the send-receipt timeout. | Same as above. | Next reply appears. |
Connector is not ready with a current authenticated and explicitly pinned outbound origin |
Inner error | A reply was attempted while the connection was down for more than 30 s. | Restore connectivity; OpenClaw core retries. | Reply appears after reconnect. |
Connector socket closed before backend receipt |
Inner error | The connection dropped while sending. | Transient; OpenClaw core retries. | Reply appears. |
Connector transport stopped before backend receipt |
Inner error | The channel stopped (restart, disable) while sending. | Transient; OpenClaw core retries. | Reply appears. |
Backend rejected outbound intent: <reason> |
Inner error, permanent (not retried) | reason source_expired: the triggering message is older than the 30-day window; channel_unavailable: the conversation is no longer available to the agent; identity_conflict: the same reply id was reused with different text. | Nothing to retry for source_expired; for channel_unavailable re-add the agent or use an active conversation; identity_conflict indicates a bug: contact support. | — |
Backend outbound receipt omitted message identity |
Inner error | Unexpected service response. | Contact support. | — |
Backend returned an invalid outbound status receipt |
Inner error | Unexpected service response. | Contact support. | — |
Backend did not accept outbound intent |
Inner error | Unexpected service response. | Contact support. | — |
The Octopus Prime reply connector changed during this turn; delivery was not started. |
Gateway log (not retried) | The channel account restarted or was re-pinned during the agent's turn. | Ask the agent again once the connector is READY. | Reply appears. |
Octopus Prime outbound currently supports one durable text part only |
Send error | The agent tried to send media or a multi-part message. | Agents reply with plain text only; no files or media. | Text replies arrive. |
Durable outbound, parent event, and channel identities are required |
Send error | The agent tried to send something that is not a reply to an Octopus Prime message (for example a proactive send). | Agents can only answer messages they received from Octopus Prime. | — |
Octopus Prime outbound requires the durable message adapter |
Send error | A non-durable send path was used. | Only replies to received messages are supported. | — |
Octopus Prime replies require durable core-managed delivery |
Send error | A non-durable send path was used. | Only replies to received messages are supported. | — |
Build 10 pilot outbound supports only the octopus-prime default account |
Send error (permanent) | A send targeted a non-default account. | Use only the default account. | — |
Build 10 pilot outbound requires a channel target |
Send error (permanent) | A send targeted something other than an Octopus Prime conversation. | Only reply within the conversation the message came from. | — |
Octopus Prime host runtime is not bound |
Gateway startup log | Startup race inside the Gateway. | openclaw gateway restart; if it persists reinstall the plugin package with --force. | Connector READY. |
Octopus Prime host runtime is unavailable |
Gateway startup log | Startup race or failed plugin load. | openclaw gateway restart; check openclaw plugins inspect octopus-prime --runtime --json. | Connector READY. |
Octopus Prime connector account is already running |
Gateway startup log | Double start of the channel account. | openclaw gateway restart. | Connector READY. |
Octopus Prime transport is already started |
Gateway startup log | Double start of the transport. | openclaw gateway restart. | Connector READY. |
prepared payload capability mismatch (thread) |
Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0 (openclaw plugins install <plugin package> --force). | Replies arrive. |
The reply channel changed or cannot preserve its sender |
Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0. | Replies arrive. |
Delivery platform claim was lost |
Gateway log | Plugin build older than 1.1.0. | Install plugin 1.1.0. | Replies arrive. |
Plugin config repair could not be inspected |
Output of openclaw plugins install --force or openclaw plugins update on OpenClaw 2026.9.8 (reported in the plugin's own notes; not OpenClaw documentation wording) | Replacing a plugin build that lacks a Doctor contract. | Install plugin 1.1.0, which ships the Doctor contract. | The install completes; openclaw plugins inspect octopus-prime --runtime --json shows loaded. |
Connection close codes
Close codes of the plugin's WebSocket to wss://api.octopusprimeai.com/api/connector/ws, shown as octopus-prime connector socket closed (code <N>); reconnecting in <n> seconds. The plugin always reconnects with backoff 2, 4, 8, then every 15 s.
| Code | Where | Cause | Fix | Verify |
|---|---|---|---|---|
4401 |
Close code in octopus-prime connector socket closed (code 4401) | The connection carried no credential. | Rerun setup with a new code (channels.octopus-prime.connectorToken is missing). | Connector READY. |
4403 |
Close code in octopus-prime connector socket closed (code 4403) | Credential unknown or revoked, organization archived, or replaced by a newer connection using the same credential (two Gateways or processes with the same config). | Revoked/rotated: Connect OpenClaw (or New setup code) and rerun setup. Duplicate: stop the second Gateway/profile using the same config, or give it its own connector. Archived organization: an Owner restores it. | No repeating 4403; connector READY. |
4426 |
Close code; connector chip INCOMPATIBLE | Protocol token not accepted, or no protocol negotiation within 5 s. | Install the plugin package Octopus Prime currently provides (plugin 1.1.0 sends 2026.9.7); check that nothing delays the connection start. | Connector READY. |
1002 |
Close code | Malformed frame, or the agent roster was rejected (more than 1000 agents, id longer than 128 characters, duplicate ids, name longer than 256, description longer than 4096). | Fix agent ids, names or descriptions in OpenClaw; update the plugin if frames are malformed. | Connector READY; agents listed. |
1001 |
Close code | No frame for 75 s (idle connection). | Check proxies or firewalls that cut idle or long-lived connections; heartbeats run every 25 s. | No repeating 1001. |
1011 |
Close code | Service-side error. | Transient; the plugin reconnects. Contact support if it repeats. | Connector READY. |
1012 |
Close code | The Octopus Prime service restarted. | Nothing; the plugin reconnects automatically. | Connector READY. |
1006 |
Close code reported locally when the connection dropped without a close frame | Network drop. | Nothing if occasional; the plugin reconnects. | Connector READY. |
Delivery failure reasons
Reason values behind a FAILED (or expired/cancelled) delivery chip.
| Reason | Where | Cause | Fix | Verify |
|---|---|---|---|---|
ack_timeout |
Chip FAILED | The plugin did not acknowledge within 20 s on 5 offers (Gateway reachable but not processing, plugin errors). | Check openclaw channels logs --channel octopus-prime and openclaw logs --follow; fix the plugin or Gateway; send the message again. | A new message reaches RESPONDED. |
reply_timeout |
Chip FAILED after WORKING or RECEIVED | No progress for 10 minutes (no reply and no Working signal), or the Gateway was down past that limit. | Check the agent's model/provider and tools in openclaw logs --follow. A late reply is still saved and shown. | Next message reaches RESPONDED. |
route_unavailable |
Chip FAILED | The agent is inactive, no longer announced by its Gateway, no longer in the conversation, or the conversation is archived. | Restore the agent in OpenClaw or in the conversation; use an active conversation. | Next message reaches RESPONDED. |
route_identity_changed |
Chip FAILED | The agent's OpenClaw id changed after the message was accepted. | Keep OpenClaw agent ids stable; message the agent again. | Next message reaches RESPONDED. |
stable_identity_missing |
Chip FAILED | The sender or the agent's OpenClaw id was missing. | Send again; contact support if it repeats. | — |
sender_access_revoked |
Chip FAILED | The sender was deleted, deactivated or is no longer a participant. | Nothing; the message is not delivered on purpose. | — |
source_sender_mismatch |
Chip FAILED | The stored sender no longer matches the message. | Contact support if it repeats. | — |
source_retention_expired |
Delivery state expired | The message passed the 30-day window before the Gateway came back. | Send a new message. | — |
message_removed |
Delivery state cancelled | The source message was removed. | Nothing. | — |
sender_account_revoked |
Delivery state cancelled | The sender deleted their account; their queued agent deliveries are cancelled. | Nothing. | — |
connector_rejected |
last_error of a FAILED delivery | The plugin rejected the delivery (for example Agent is not currently announced by this connector). | See the plugin rejection reason in openclaw channels logs --channel octopus-prime. | Next message reaches RESPONDED. |
Service errors (HTTP detail)
detail texts returned by the Octopus Prime service, grouped by area.
Setup-code exchange (POST /api/connector/bootstrap)
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 404 | Invalid or used setup code |
setup-code exchange | The code was mistyped, already used, or replaced by a newer code. | Web app: New setup code; rerun setup within 15 minutes. | Setup succeeds. |
| 410 | Setup code expired |
setup-code exchange | More than 15 minutes passed. | New setup code; rerun setup. | Setup succeeds. |
| 404 | Connector not found |
setup-code exchange | The connector no longer exists. | Connect OpenClaw again and use its code. | Setup succeeds. |
| 404 | Connector revoked |
setup-code exchange | The connector was revoked. | Connect OpenClaw (new connector) and use its code. | Setup succeeds. |
| 426 | Unsupported OpenClaw plugin API <v>. Supported: ['2026.9.7'] |
setup-code exchange (checked before the code is used up) | The plugin sends a protocol token the service does not accept (an unsupported plugin build). <v> is the plugin's token, not your OpenClaw version. | Install the plugin package Octopus Prime currently provides (1.1.0 sends 2026.9.7); the same code still works if not expired. | Setup succeeds. |
Organization
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | Organization is archived |
any organization action, including setup | The organization was archived. | An Owner restores the organization. | Actions work again. |
| 403 | Only an owner can access an archived organization |
opening an archived organization | Archived organizations are visible to Owners only. | Ask an Owner. | — |
| 422 | Organization name is required |
create or rename organization | Empty name. | Provide a name. | — |
| 403 | Only an owner can archive an organization |
archive organization | Role too low. | Ask an Owner. | — |
| 409 | Settle or cancel organization billing before archiving |
archive organization | An active subscription exists. | Cancel or settle billing first. | — |
| 403 | Only an owner can restore an organization |
restore organization | Role too low. | Ask an Owner. | — |
| 403 | Only an owner can close an organization |
close organization | Role too low. | Ask an Owner. | — |
Session, Terms and membership
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 401 | Not authenticated |
any signed-in action | Missing or expired session (sessions last 7 days). | Sign in again. | — |
| 403 | Cross-origin write refused |
browser write from another site | Requests must come from the official app. | Use https://app.octopusprimeai.com or the mobile apps. | — |
| 428 | Accept the Terms of Use before posting or uploading |
posting, uploading, scheduling | Terms of Use not accepted. | Accept the Terms in the app (I agree & continue). | Posting works. |
| 403 | Insufficient role |
admin actions | Your role does not allow this. | Ask an Owner or Admin. | — |
| 403 | Not a member of this organization |
any organization action | You are not an active member. | Accept the invitation or ask to be invited. | — |
| 403 | Account unavailable |
any action after account changes | The account is deleted or deactivated. | Sign in again; contact an Owner if deactivated. | — |
| 409 | Account changed |
any action | Account state changed during the request. | Retry. | — |
| 404 | Organization not found |
any organization action | Unknown or inaccessible organization. | Switch to an organization you belong to. | — |
Sign-in
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 401 | Invalid Apple identity token |
Sign in with Apple | The Apple sign-in could not be verified. | Retry sign-in. | — |
| 401 | Invalid Google identity token |
Sign in with Google | The Google sign-in could not be verified. | Retry sign-in. | — |
| 401 | Verified Apple email required for new sign-in |
first Apple sign-in | New accounts need a verified e-mail from the provider. | Use an Apple ID with a verified e-mail, or sign in with Google. | — |
| 401 | Verified Google email required for new sign-in |
first Google sign-in | New accounts need a verified e-mail. | Use a verified Google account. | — |
| 401 | Apple account ownership conflict |
Apple sign-in | The Apple identity is linked differently than expected. | Sign in with the provider and e-mail used originally; contact support if it persists. | — |
| 401 | Google account ownership conflict |
Google sign-in | As above. | As above. | — |
| 401 | Apple account ownership changed; retry sign-in |
Apple sign-in | Linking changed during sign-in. | Retry sign-in. | — |
| 401 | Google account ownership changed; retry sign-in |
Google sign-in | Linking changed during sign-in. | Retry sign-in. | — |
| 401 | Ambiguous Apple account |
Apple sign-in | The identity matches more than one account. | Contact support. | — |
| 401 | Ambiguous Google account |
Google sign-in | As above. | Contact support. | — |
Messages
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | Message is empty |
send message or schedule | No text and no files. | Write something. | — |
| 403 | This conversation is blocked |
send in a DM | One of the two people blocked the other. | The blocker can unblock in Blocked users. | — |
| 404 | Parent message not found |
reply in thread | The thread root is gone (for example past 30 days). | Post a new message. | — |
| 404 | Channel not found |
any conversation action | Unknown conversation or no access. | Check membership. | — |
| 409 | Client message ID already identifies a different message |
send message | The same client_message_id was reused with different content. | Use a new client_message_id for new content. | — |
| 422 | Message cursor requires before and before_id |
history paging | Incomplete paging cursor. | Send both values. | — |
| 410 | Source message expired |
retry of a delivery | The message is past the 30-day window. | Send a new message. | — |
| 404 | Delivery not found |
retry of a delivery | Unknown delivery. | — | — |
Direct messages
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | Pick a person or an agent |
start a DM | Nothing selected. | Choose a person or an agent. | — |
| 400 | Cannot DM yourself |
start a DM | You picked yourself. | Pick someone else. | — |
| 400 | User is not an active member |
start a DM | The person is not an active member. | Invite or reactivate them. | — |
| 400 | Agent is not available |
start an agent DM | The agent is inactive, revoked or no longer announced by its Gateway. | Make sure its Gateway is connected and the agent exists in OpenClaw. | Agent DM opens. |
| 403 | Cannot start a conversation with this user |
start a DM | A block exists between the two people. | The blocker can unblock. | — |
Plans and billing
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | This organization's plan allows N active human(s) |
invite, accept invitation, reactivate member | The people limit of the plan (plus add-ons) is reached. | Owner/Admin adds Extra human add-ons or upgrades. | The action succeeds. |
| 409 | This organization's plan allows N AI agent(s) |
new agent DM, add agent to channel | The agent limit is reached. | Owner/Admin adds Extra AI agent add-ons or upgrades (maximum 50). | The action succeeds. |
| 409 | An organization can have at most 50 AI agents. Contact us to raise this limit. |
plan or add-on change | More than 50 agents requested. | Contact support@octopusprimeai.com. | — |
| 402 | Your organization's subscription is inactive. An owner or admin must activate billing. |
posting after the trial ended or payment lapsed | No active subscription. | An Owner/Admin chooses a plan in the web app. | Posting works. |
| 400 | Unknown plan |
checkout | Invalid plan. | Choose Starter, Pro or Business. | — |
| 409 | A checkout for this organization is being opened. Try again in a moment. |
checkout | Another checkout is in progress. | Wait and retry. | — |
| 409 | Subscription already active |
checkout | Already subscribed. | Change the plan instead. | — |
| 409 | No billing account yet |
payment settings | No subscription created yet. | Choose a plan first. | — |
| 409 | No active subscription. Choose a plan at checkout. |
plan change | No subscription to change. | Choose a plan. | — |
Channels
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | Channel agent limit (5) reached |
add agent to channel | The channel already has 5 agents. | Remove an agent or use another channel. | — |
| 403 | Manager is not assigned to this channel |
channel management | Managers manage only channels they are in. | Ask an Owner/Admin. | — |
| 400 | Invalid channel type |
create channel | Unsupported type. | — | — |
| 409 | Direct messages cannot be administered as channels |
channel management on a DM | DMs have no channel settings. | — | — |
| 409 | Restore the channel before editing it |
edit archived channel | The channel is archived. | Restore it first. | — |
| 422 | Channel name is required |
create or rename channel | Empty name. | Provide a name. | — |
| 409 | Organization-wide channels cannot be private |
channel settings | #announcements is organization-wide. | — | — |
| 409 | Organization-wide channels cannot be archived |
archive channel | #announcements cannot be archived. | — | — |
| 422 | No channel changes supplied |
channel update | Nothing changed. | — | — |
| 400 | User is not an active member of this organization |
add member to channel | The person is not an active member. | Invite or reactivate them first. | — |
| 403 | Only an owner or admin can assign an Owner, Admin, or Manager to a channel |
channel membership | Managers cannot add elevated roles. | Ask an Owner/Admin. | — |
| 403 | Only an owner or admin can unassign an Owner, Admin, or Manager from a channel |
channel membership | Managers cannot remove elevated roles. | Ask an Owner/Admin. | — |
| 409 | Channel changed |
channel update | Concurrent change. | Reload and retry. | — |
| 404 | Agent not found |
agent actions | Unknown agent. | Check the agent list in OpenClaw Agents. | — |
Invitations
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | User is already a member |
invite | Already in the organization. | — | — |
| 409 | An invitation is already pending for this email |
invite | An open invitation exists. | Wait for acceptance or withdraw it first. | — |
| 404 | Invitation not found or already used |
accept invitation | Withdrawn, used or unknown. | Ask for a new invitation. | — |
| 403 | This invitation was sent to a different email |
accept invitation | Signed in with another address (common with Apple Hide My Email). | Sign in with the invited address, or ask to invite the address you use. | — |
| 410 | Invitation expired |
accept invitation | Older than 14 days. | Ask for a new invitation. | — |
| 403 | Ownership invitation lacks verified authority; request a new owner-issued invitation |
accept Owner invitation | The Owner invitation is not valid. | Ask a current Owner to invite you again. | — |
| 409 | This owner invitation was withdrawn because the person who sent it is no longer an owner of this organization. Ask a current owner to invite you again. |
accept Owner invitation | The inviter is no longer an Owner. | Ask a current Owner. | — |
Roles and members
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | Invalid role |
role change | Unknown role. | Use owner, admin, manager or member. | — |
| 409 | Cannot remove the sole active owner |
role change or removal | The organization must keep one Owner. | Make someone else Owner first. | — |
| 409 | Cannot deactivate the sole owner |
deactivate member | As above. | Make someone else Owner first. | — |
| 403 | Only an owner can assign ownership |
role change | Admins cannot grant Owner. | Ask an Owner. | — |
| 403 | Only an owner can change ownership |
role change | Admins cannot change an Owner. | Ask an Owner. | — |
| 400 | Invalid status |
member status change | Unknown status. | — | — |
| 409 | Deleted accounts cannot be reactivated |
reactivate member | The person deleted their account. | Invite their new account. | — |
| 404 | Member not found |
member actions | Unknown member. | — | — |
Account deletion
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 409 | You are the only owner of '<org>'. Make another member an owner before deleting your account. |
delete account | Sole Owner of an organization with other active members. | Make another member an Owner, then delete. | Deletion succeeds. |
| 409 | Settle or cancel billing for '<org>' before deleting your account. |
delete account | Active billing on an organization you would close. | Cancel or settle billing first. | Deletion succeeds. |
| 409 | A checkout is open for '{name}'. Try again after it expires in {N minute(s)}. |
delete account | A checkout session is open. | Wait the stated time. | Deletion succeeds. |
| 409 | Membership changed; retry account deletion |
delete account | Membership changed during deletion. | Retry. | Deletion succeeds. |
Scheduled messages
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | Messages can be scheduled only in a channel or an agent direct message |
create schedule | Person-to-person DM. | Use a channel or agent DM. | — |
| 400 | Choose a template or write a message |
create schedule | Neither text nor template. | Provide one. | — |
| 400 | A scheduled message can be at most 4000 characters |
create schedule | Text over 4,000 characters. | Shorten it. | — |
| 400 | Invalid start time |
create schedule | Unparseable time. | Pick a valid time. | — |
| 400 | Choose a time in the future |
create schedule | Start time not at least 30 s ahead. | Pick a time further ahead. | — |
| 400 | Choose when to send the message |
create schedule | No time given for a one-time schedule. | Pick a time. | — |
| 400 | Start time is too far out (max 90 days) |
create schedule | More than 90 days ahead. | Pick an earlier time. | — |
| 409 | This organization already has 20 scheduled messages. Delete one before adding another. |
create schedule | 20 active or paused schedules exist. | Delete one. | — |
| 409 | Client schedule ID already identifies a different schedule |
create schedule | Reused id with different content. | Retry as a new schedule. | — |
| 409 | Only an active schedule can be paused |
pause | Not active. | — | — |
| 403 | Only the person who created this schedule can resume it |
resume | Not the creator. | Ask the creator, or create a new schedule. | — |
| 409 | Only a paused schedule can be resumed |
resume | Not paused. | — | — |
| 409 | This one-time schedule's time has passed |
resume | The one-time slot is in the past. | Create a new schedule. | — |
| 422 | Status must be paused or active |
update schedule | Invalid status value. | — | — |
| 404 | Template not found |
schedule from template | Template deleted. | Pick another template. | — |
| 404 | Schedule not found |
schedule actions | Deleted or unknown. | — | — |
Report and block
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | You can't report your own message |
report | — | — | — |
| 409 | A moderator already removed this message |
report | Already handled. | — | — |
| 400 | You can't report yourself |
report person | — | — | — |
| 404 | Person not found in this conversation |
report person | The person is not in that conversation. | — | — |
| 404 | Message not found |
report message | Message gone (for example past 30 days). | — | — |
| 400 | Cannot block yourself |
block | — | — | — |
| 404 | Person not found |
block | Unknown person. | — | — |
| 400 | Agents can't be blocked. Report the message instead, or ask an owner or admin to remove the agent. |
block an agent | Agents are not blockable. | Report the message or ask an Owner/Admin to remove the agent from the channel. | — |
Files
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | Upload one file per request |
upload | More than one file in one upload. | Upload files one by one. | — |
| 413 | File "<name>" is larger than 5 MB |
upload | Over 5 MB. | Shrink or split the file. | — |
| 400 | A message can include at most 5 files; this one has N |
send message | More than 5 attachments. | Send in several messages. | — |
| 400 | Duplicate attachments are not allowed |
send message | Same file attached twice. | Remove the duplicate. | — |
| 400 | One or more attachments are unavailable in this channel |
send message | Attachment uploaded elsewhere or expired. | Upload again in this conversation. | — |
| 400 | This file type is not allowed |
upload | Blocked type (executables, scripts, HTML, SVG, XML). | Use an allowed format or share as text. | — |
| 400 | Unsupported file type |
upload | Unrecognized type. | Use an allowed format. | — |
| 410 | This file has expired |
download | Older than 7 days. | Ask the sender to share it again. | — |
| 404 | File not found |
download | Unknown file. | — | — |
| 403 | Forbidden |
download | No access to that conversation. | — | — |
Search
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 422 | Search query is required |
search | Empty query. | Type a query. | — |
Notification settings
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 422 | mode must be one of all|mentions|mute |
notification settings | Invalid mode. | Use all, mentions or mute. | — |
| 422 | time must be HH:MM (24-hour) |
quiet hours | Invalid time format. | Use HH:MM. | — |
| 422 | timezone is required |
quiet hours | Missing time zone. | Provide an IANA time zone. | — |
| 422 | invalid IANA timezone |
quiet hours | Unknown time zone. | Use a name like America/Phoenix. | — |
Voice
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 400 | Recording too short — try again |
dictation | Clip under 2 KB. | Record longer. | — |
| 413 | Audio exceeds the 25 MB limit |
dictation | Clip over 25 MB. | Record a shorter clip. | — |
| 502 | Could not transcribe audio |
dictation | Transcription failed. | Retry. | — |
| 400 | Nothing to read aloud |
read aloud | Message has no text. | — | — |
| 502 | Could not generate audio |
read aloud | Speech generation failed. | Retry. | — |
Health Watch
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 404 | Health Watch incident not found |
acknowledge incident | Unknown or expired incident (finished incidents are kept 7 days). | Refresh Health Watch. | — |
| 409 | Health Watch incident is already terminal |
acknowledge incident | The incident already closed. | Nothing to do. | — |
Service health
| HTTP | Exact detail |
Trigger | Cause | Fix | Verify |
|---|---|---|---|---|---|
| 503 | Service unavailable |
GET /api/health/ready | The service is not ready (starting or a dependency is down). | Wait and retry. | GET /api/health/ready returns {"status":"ready"}. |
| 503 | Database unavailable |
any request | Temporary storage outage. | Retry after a short wait. | — |
App messages
Banners, toasts and inline messages in the web and mobile apps.
| Exact text | Where | Cause | Fix | Verify |
|---|---|---|---|---|
Live updates off — checking for new messages every few seconds |
Web banner | The app is refreshing open conversations every few seconds instead of receiving live pushes. | Nothing; new messages still appear within seconds. | — |
Live updates off · open chats refresh every few seconds |
iPhone banner | As above. | Nothing. | — |
Reconnecting… |
Web banner | A refresh of the conversation failed. | Wait; it clears on the next successful refresh. Check your internet connection if it stays. | — |
Could not load connectors |
OpenClaw Agents dialog (with Retry) | The connector list could not be loaded. | Retry; sign in again if your session expired. | — |
Could not create connector |
OpenClaw Agents dialog | Connect OpenClaw failed (or the service detail is shown instead). | Retry; check you are Owner/Admin. | — |
Could not create a new setup code |
OpenClaw Agents dialog | New setup code failed. | Retry; check you are Owner/Admin. | — |
Could not revoke connector |
OpenClaw Agents dialog | Revoke failed. | Retry; check you are Owner/Admin. | — |
Connector revoked |
OpenClaw Agents dialog (success) | The connector was revoked. | Disable or uninstall the plugin on that Gateway to stop its reconnect attempts. | — |
Could not copy. Select the text and copy it manually. |
OpenClaw Agents dialog | Clipboard access failed. | Use View or manually copy the prompt. | — |
A valid HTTPS backend address is required to prepare connection instructions. |
OpenClaw Agents dialog | The app could not build the setup prompt. | Reload the web app; contact support if it persists. | — |
Could not load agents. |
iPhone agents list (with Retry) | The agent list could not be loaded. | Retry. | — |
No agents connected |
iPhone agents list | No connected Gateway has announced agents. | Connect a Gateway (web app) and check it is READY. | — |
"{name}" is {size} — over the 5 MB limit, so it was not attached. |
Composer | File over 5 MB. | Use a smaller file. | — |
"{name}" is too large to upload (the limit is 5 MB), so it was not attached. |
Composer | Upload refused as too large. | Use a smaller file. | — |
This file has expired. |
Message attachment | File older than 7 days. | Ask the sender to share it again. | — |
You cannot post here |
Composer | No permission to post in this conversation. | Ask a channel manager or Owner/Admin. | — |
Accept the Terms of Use before posting |
Composer | Terms not accepted. | Accept the Terms (I agree & continue). | — |
Could not send message |
Composer | Sending failed. | Retry; check connection and subscription status. | — |
Your free trial has ended |
Billing / paywall | The 7-day trial ended without a plan. | An Owner/Admin chooses a plan in the web app. | Posting works. |
Subscription inactive |
Billing / paywall | No active subscription. | An Owner/Admin chooses or fixes the plan. | Posting works. |
Access is paused for this organization. Please ask an owner or admin to choose a plan. |
Paywall (members) | Trial ended or subscription inactive. | Ask an Owner/Admin. | Posting works. |
Payment failed — please update your card |
Billing | A payment failed; the 7-day grace period runs. | Owner/Admin updates the payment method in the web app. | Notice disappears. |
Access paused — trial ended. Open Settings. |
iPhone banner | Trial ended. | Owner/Admin chooses a plan on the web. | Posting works. |
Access paused — subscription inactive. Open Settings. |
iPhone banner | Subscription inactive. | Owner/Admin fixes billing on the web. | Posting works. |
Enter a valid email address (name@company.com). |
Invite people | Malformed address. | Correct the address. | — |
That email domain can’t receive invitations. Use a real work email. |
Invite people | The domain is not accepted for invitations. | Use another address. | — |
Your account was deleted |
Sign-in screen | You deleted your account; all sessions ended. | Signing in again starts a new, empty account. | — |
You have been signed out on every device. Signing in again starts a new account. |
Sign-in screen after deletion | Account deletion. | — | — |
Health Watch is available only to an Owner or Admin of an active organization. |
iPhone Health Watch | Role too low or organization inactive. | Ask an Owner/Admin. | — |
No gateways are connected. |
Health Watch | No connector exists. | Connect a Gateway. | — |
Microphone access was denied |
Dictation | Microphone permission missing. | Allow microphone access for the app or browser. | — |
Recording failed — try again |
Dictation | Recording error. | Retry. | — |
Didn't catch that — try again |
Dictation | No speech recognized. | Speak again. | — |
Transcription failed |
Dictation | Transcription error. | Retry. | — |
Playback failed |
Read aloud | Audio playback error. | Retry. | — |
Could not read aloud |
Read aloud | Speech generation error. | Retry. | — |
Message from a blocked user hidden. |
Conversation | You blocked the sender. | Unblock in Blocked users if wanted. | — |
When the fix does not work
- Collect a sanitized diagnostics bundle on the Gateway host:
openclaw triage --non-interactive. It collects diagnostics without launching an agent; the archive excludes secrets, tokens, raw chat payloads and raw logs (OpenClaw docs: cli/triage). - E-mail support@octopusprimeai.com with the exact error text, the time it happened (with time zone), what you already tried, and the bundle. Never include setup codes, connector credentials or session tokens.