Error codes
When HeyCMO refuses a request, the answer says why with a code. Each code has its own section on this page, and the docs_url of the answer opens it. The MCP server and the CLI pass the same codes on.
The shape of an error
Errors are application/problem+json (RFC 9457). For example:
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://heycmo.ai/problems/approval_pending",
"title": "An approval already covers this target",
"status": 409,
"code": "approval_pending",
"detail": "This artifact already waits for a person.",
"retryable": false,
"docs_url": "https://heycmo.ai/docs/errors#approval_pending",
"approval_url": "https://app.heycmo.ai/approve/...",
"request_id": "req_..."
}
| Field | What it holds |
|---|---|
code | One of the codes below. Make your code read this field, not title or detail. |
status | The HTTP status. |
title, detail | Words for people. They can change. |
retryable | True when the same request can work later, after the step in the Retry column. |
hint | The next step, when there is one. |
docs_url | The section of this page for the code. |
approval_url, action_url, connect_url | A link for a person, when a person's step can clear the error. Give it to them; an agent cannot use it. Over MCP, only approval_url is passed on. |
errors | For invalid_request: each field that failed, with its path and message. |
items | For a week approval that failed: each approval ID with its own code. One failed item stops the whole week. |
request_id | Give it to HeyCMO support when you ask about an error. |
When only a person can clear it
Codes marked A person must act wait for a person on app.heycmo.ai, most often with a passkey (Face ID, fingerprint or your phone). An agent cannot approve, raise a level, resume, connect a platform, pay or state a fact. Do not retry these codes in a loop. Give the person the link from the answer, then read the result later. For most of these codes the CLI prints the link and exits 4. For credits_required, not_routed, level_too_low and payload_changed it exits 1.
The MCP server passes on code, title, status, detail, retryable, request_id, approval_url, errors and items. It does not pass on hint, docs_url, action_url or connect_url. When a link is missing, send the person to app.heycmo.ai.
All codes
| Code | Status | Retry | Who clears it |
|---|---|---|---|
invalid_request | 400 | No | Fix the request |
unauthenticated | 401 | No | Fix the request |
step_up_required | 401 | After the check | A person must act |
otp_required | 401 | After the code | A person must act |
credits_required | 402 | After the plan allows it | A person must act |
card_required | 403 | After a card or invoice | A person must act |
passkeys_required | 403 | After enrollment | A person must act |
insufficient_scope | 403 | No | Fix the request |
human_required | 403 | No | A person must act |
not_routed | 403 | No | A person must act |
level_too_low | 403 | No | A person must act |
class_blocked | 403 | No | No one |
channel_not_enabled | 403 | No | No one |
feature_not_enabled | 403 | No | No one |
workspace_unclaimed | 403 | No | A person must act |
invite_required | 403 | No | Fix the request |
domain_unverified | 403 | After verification | A person must act |
not_found | 404 | No | Fix the request |
in_progress | 409 | Yes | Try again later |
approval_pending | 409 | No | A person must act |
already_decided | 409 | No | No one |
payload_changed | 409 | No | A person must act |
connection_required | 409 | After a person reconnects | A person must act |
kb_not_ready | 409 | Yes | Try again later |
claims_unsupported | 409 | No | Fix the request |
topic_conflict | 409 | No | Fix the request |
slot_unavailable | 409 | No | Fix the request |
approval_expired | 410 | No | Fix the request |
window_closed | 410 | No | No one |
link_used | 410 | No | No one |
idempotency_key_reused | 422 | No | Fix the request |
workspace_paused | 423 | After a resume | A person must act |
rate_limited | 429 | After Retry-After | Try again later |
platform_error | 502 | When the hint says so | Try again later |
sandbox_unavailable | 503 | Yes | Try again later |
service_unavailable | 503 | Yes | Try again later |
Each code
invalid_request
- Status
- 400
- Retry
- No
- Who clears it
- Fix the request
- What it means
- The body or the query does not match the schema.
errorslists each field with itspathandmessage. A week approval also uses it for a piece the signer has not opened, a piece that cannot join a week signature, or a time outside the week. Over MCP, it also means the sign-in reaches more than one workspace and the client named none. - What to do
- Correct the fields that
errorsnames, then send the request again. Over MCP, send theHeyCMO-Workspaceheader.
unauthenticated
- Status
- 401
- Retry
- No
- Who clears it
- Fix the request
- What it means
- The token is missing, expired or not valid, or it was made for another resource. The
WWW-Authenticateheader points to the resource metadata, which namesauth.heycmo.ai. An MCP client whose access an owner revoked also gets this code. - What to do
- Sign in again:
heycmo login, your MCP client's sign-in, or a valid API key inHEYCMO_TOKEN. A client that an owner revoked is not connected again by a new sign-in. Ask HeyCMO support.
step_up_required
- Status
- 401
- Retry
- After the check
- Who clears it
- A person must act
- What it means
- A person's web session or CLI login called a route that needs a fresh passkey check.
- What to do
- The person does the passkey check on
app.heycmo.ai. The CLI prints the link and exits 4.
otp_required
- Status
- 401
- Retry
- After the code
- Who clears it
- A person must act
- What it means
- A regulated decision has a passkey check but no valid code from an authenticator app. v1 does not send this code: it approves a money, health or crypto piece one at a time with the passkey, and shows a warning.
- What to do
- The person enters the 6-digit code, or a recovery code, on
app.heycmo.ai.
credits_required
- Status
- 402
- Retry
- After the plan allows it
- Who clears it
- A person must act
- What it means
- The run does not fit what is left in the plan this month. In v1 the
detailcounts pieces, for example new pages or refreshes. - What to do
- Start it next month, or start a smaller job. The workspace owner talks to HeyCMO about the plan. v1 has no top-ups.
card_required
- Status
- 403
- Retry
- After a card or invoice
- Who clears it
- A person must act
- What it means
- The workspace's first live write, or a raise above L2, needs a card on file or a paid invoice. It is off for invited design partners until their first invoice.
- What to do
- The owner adds a card or pays the invoice. An agent cannot do this.
passkeys_required
- Status
- 403
- Retry
- After enrollment
- Who clears it
- A person must act
- What it means
- A raise to L3 or L4 needs two registered passkeys or two owners. v1 stops at L2, so a raise past L2 answers
feature_not_enabledinstead. - What to do
- A person registers a second passkey on
app.heycmo.ai.
insufficient_scope
- Status
- 403
- Retry
- No
- Who clears it
- Fix the request
- What it means
- The token does not hold an agent scope that the route needs. The
WWW-Authenticateheader names the scope. - What to do
- Sign in again and ask for that scope, or use an API key that has it.
human_required
- Status
- 403
- Retry
- No
- Who clears it
- A person must act
- What it means
- An API key, an MCP sign-in or another agent client called a route that only a person may use, such as approving or connecting a platform.
- What to do
- Do not retry. Give the person the link from the
hintor fromapproval_url. They act onapp.heycmo.ai.
not_routed
- Status
- 403
- Retry
- No
- Who clears it
- A person must act
- What it means
- The action class is not routed to this person, so they cannot decide, raise or edit it.
- What to do
- Ask a person the class is routed to, or ask an owner to route it.
level_too_low
- Status
- 403
- Retry
- No
- Who clears it
- A person must act
- What it means
- The class's level in effect is L0 or L1 and the request is a live write. HeyCMO refuses it and does not queue it.
- What to do
- Keep the piece as a draft, or ask a person to raise the class to L2 on
app.heycmo.ai.
class_blocked
- Status
- 403
- Retry
- No
- Who clears it
- No one
- What it means
- HeyCMO never moves money, changes permissions on a connected platform, or accepts third-party terms.
- What to do
- Do it outside HeyCMO, on the platform itself.
channel_not_enabled
- Status
- 403
- Retry
- No
- Who clears it
- No one
- What it means
- The channel is not open: it waits for the platform's approval, or the plan does not have it. In v1 HeyCMO posts to GitHub pull requests, Webflow and X. LinkedIn gets copy-ready drafts only.
- What to do
- Use another connection, or post the copy-ready draft yourself.
feature_not_enabled
- Status
- 403
- Retry
- No
- Who clears it
- No one
- What it means
- The route or job is off for this workspace. In v1 this covers, for example, a raise past L2, veto and undo, the jobs
full_auditandship_to_launch, email,POST /ask, exports and billing changes. - What to do
- Do not retry. Use a v1 job or route; the
jobs://catalogresource andheycmo jobs listshow the v1 jobs.
workspace_unclaimed
- Status
- 403
- Retry
- No
- Who clears it
- A person must act
- What it means
- Nobody has claimed the workspace yet, so it runs internal work only.
- What to do
- The person opens the claim link from their email and registers a passkey.
invite_required
- Status
- 403
- Retry
- No
- Who clears it
- Fix the request
- What it means
- Signing up, or a first MCP sign-in that makes a workspace, needs a valid invite code until Apr 26, 2027. The
detailsays if the code is unknown, already used, expired, or for another site. - What to do
- Send a valid code:
heycmo signup --invite <code>, or theHeyCMO-InviteandHeyCMO-Domainheaders over MCP. Only HeyCMO gives out codes.
domain_unverified
- Status
- 403
- Retry
- After verification
- Who clears it
- A person must act
- What it means
- The workspace signed up with a personal email address and has not verified its site domain, so live writes wait.
- What to do
- A person verifies the domain on
app.heycmo.ai.
not_found
- Status
- 404
- Retry
- No
- Who clears it
- Fix the request
- What it means
- The ID does not exist, or it belongs to a workspace your token does not reach. HeyCMO gives the same answer in both cases, so nothing leaks. Over MCP, it also means the named workspace is not one this sign-in reaches.
- What to do
- Check the ID and the workspace.
in_progress
- Status
- 409
- Retry
- Yes
- Who clears it
- Try again later
- What it means
- A request with the same
Idempotency-Keyis still running. - What to do
- Wait, then send the same request with the same key. You get the result of the first one.
approval_pending
- Status
- 409
- Retry
- No
- Who clears it
- A person must act
- What it means
- An open approval already covers this target.
approval_urlpoints to it. - What to do
- Do not ask again. Give the person the link.
already_decided
- Status
- 409
- Retry
- No
- Who clears it
- No one
- What it means
- Another approver decided first.
- What to do
- Read the approval to see the result.
payload_changed
- Status
- 409
- Retry
- No
- Who clears it
- A person must act
- What it means
- The draft, pull request or CMS revision changed after the preview. The old approval is now
superseded, andapproval_urlpoints to the new one. - What to do
- Give the person the new link. They approve what they saw.
connection_required
- Status
- 409
- Retry
- After a person reconnects
- Who clears it
- A person must act
- What it means
- The write needs a connection that is missing, expired or revoked.
connect_urlis for a person. The MCP server does not pass it on. - What to do
- Give the person the link. They connect the platform on
app.heycmo.ai; the CLI commandheycmo connectonly prints the link.
kb_not_ready
- Status
- 409
- Retry
- Yes
- Who clears it
- Try again later
- What it means
- The workspace's knowledge base is not built yet, so a content job cannot start.
- What to do
- Start
knowledge_basewithmode=build, wait until it ends, then try again.
claims_unsupported
- Status
- 409
- Retry
- No
- Who clears it
- Fix the request
- What it means
- A claim in the piece has no current source in the knowledge base, for example because the fact changed or the page was removed. It is also an item code in a week approval.
- What to do
- Remove the claim or start a new draft. Only a person can state a fact, on
app.heycmo.ai.
topic_conflict
- Status
- 409
- Retry
- No
- Who clears it
- Fix the request
- What it means
- A page already covers this search, or the topic was merged into another one. The answer names the page or the topic.
- What to do
- Refresh the page that is there with
article_refresh, or pick another topic.
approval_expired
- Status
- 410
- Retry
- No
- Who clears it
- Fix the request
- What it means
- The decision came after the approval expired or after its run was canceled, so the action will never run. A calendar piece waits until Sunday 23:59 of its week; other requests wait 24 hours.
- What to do
- Ask to publish again. This makes a new approval.
window_closed
- Status
- 410
- Retry
- No
- Who clears it
- No one
- What it means
- In v1: a stop came after HeyCMO had started to post the piece, so it is too late to stop it.
- What to do
- Read the action with
get_actionorheycmo actions get. To change the piece, edit it on the platform.
link_used
- Status
- 410
- Retry
- No
- Who clears it
- No one
- What it means
- A decision already used this single-use link.
- What to do
- Open
app.heycmo.aito see the result.
idempotency_key_reused
- Status
- 422
- Retry
- No
- Who clears it
- Fix the request
- What it means
- The same
Idempotency-Keycame with a different body. - What to do
- Use a new key for a new request. Use the same key only to send the same request again.
workspace_paused
- Status
- 423
- Retry
- After a resume
- Who clears it
- A person must act
- What it means
- A person or an agent paused everything. New runs, external writes and approvals are refused. Reading, lowering a level and stopping a post still work.
- What to do
- Wait for a person to resume the workspace on
app.heycmo.ai. An agent cannot resume it.
rate_limited
- Status
- 429
- Retry
- After Retry-After
- Who clears it
- Try again later
- What it means
- Too many requests for this key, client or workspace. The
RateLimitandRateLimit-Policyheaders say when it refills. - What to do
- Wait for the time in
Retry-After, then send the request again. The CLI exits 5.
platform_error
- Status
- 502
- Retry
- When the hint says so
- Who clears it
- Try again later
- What it means
- The platform, such as GitHub, Webflow or X, still failed after retries under the same key.
- What to do
- Read the
hint, and retry only when it says so. Over MCP there is no hint: wait, then try once more at most.