HeyCMO

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_..."
}
FieldWhat it holds
codeOne of the codes below. Make your code read this field, not title or detail.
statusThe HTTP status.
title, detailWords for people. They can change.
retryableTrue when the same request can work later, after the step in the Retry column.
hintThe next step, when there is one.
docs_urlThe section of this page for the code.
approval_url, action_url, connect_urlA 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.
errorsFor invalid_request: each field that failed, with its path and message.
itemsFor a week approval that failed: each approval ID with its own code. One failed item stops the whole week.
request_idGive 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

CodeStatusRetryWho clears it
invalid_request400NoFix the request
unauthenticated401NoFix the request
step_up_required401After the checkA person must act
otp_required401After the codeA person must act
credits_required402After the plan allows itA person must act
card_required403After a card or invoiceA person must act
passkeys_required403After enrollmentA person must act
insufficient_scope403NoFix the request
human_required403NoA person must act
not_routed403NoA person must act
level_too_low403NoA person must act
class_blocked403NoNo one
channel_not_enabled403NoNo one
feature_not_enabled403NoNo one
workspace_unclaimed403NoA person must act
invite_required403NoFix the request
domain_unverified403After verificationA person must act
not_found404NoFix the request
in_progress409YesTry again later
approval_pending409NoA person must act
already_decided409NoNo one
payload_changed409NoA person must act
connection_required409After a person reconnectsA person must act
kb_not_ready409YesTry again later
claims_unsupported409NoFix the request
topic_conflict409NoFix the request
slot_unavailable409NoFix the request
approval_expired410NoFix the request
window_closed410NoNo one
link_used410NoNo one
idempotency_key_reused422NoFix the request
workspace_paused423After a resumeA person must act
rate_limited429After Retry-AfterTry again later
platform_error502When the hint says soTry again later
sandbox_unavailable503YesTry again later
service_unavailable503YesTry 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. errors lists each field with its path and message. 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 errors names, then send the request again. Over MCP, send the HeyCMO-Workspace header.

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-Authenticate header points to the resource metadata, which names auth.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 in HEYCMO_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 detail counts 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_enabled instead.
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-Authenticate header 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 hint or from approval_url. They act on app.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_audit and ship_to_launch, email, POST /ask, exports and billing changes.
What to do
Do not retry. Use a v1 job or route; the jobs://catalog resource and heycmo jobs list show 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 detail says if the code is unknown, already used, expired, or for another site.
What to do
Send a valid code: heycmo signup --invite <code>, or the HeyCMO-Invite and HeyCMO-Domain headers 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-Key is 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_url points 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, and approval_url points 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_url is 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 command heycmo connect only 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_base with mode=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.

slot_unavailable

Status
409
Retry
No
Who clears it
Fix the request
What it means
That time is not available: the piece has no time, the time has passed, the week is full for this plan, or the time moved. It is also an item code in a week approval.
What to do
Pick a later time, or the next week.

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_action or heycmo actions get. To change the piece, edit it on the platform.

idempotency_key_reused

Status
422
Retry
No
Who clears it
Fix the request
What it means
The same Idempotency-Key came 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 RateLimit and RateLimit-Policy headers 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.

sandbox_unavailable

Status
503
Retry
Yes
Who clears it
Try again later
What it means
The step runner could not start. Runs wait and retry on their own, so only a call that waits for an answer sees this code.
What to do
Send the request again later.

service_unavailable

Status
503
Retry
Yes
Who clears it
Try again later
What it means
A service the API needs to check the request is down, for example the sign-in keys or the database. The request did not run.
What to do
Send the same request again after the time in Retry-After.