Errors and log codes

Every error the SDKs throw has a code, and the codes are the same in TypeScript, Python, Go and the HTTP API. Each message says what failed and the fix in one clause, and ends with a link to the code's entry on this page:

wakeshift: start_crawl subscribed to crawl.finished, which isn't in its subscribes. Add the event to the tool's subscribes. https://wakeshift.ai/docs/errors#undeclared_subscribe

Messages never contain a key, a token, a payload or your own code's error messages.

Classes

Catching APIError catches outages too. Check one code with isWakeshiftError(err, "timeout") in TypeScript (it narrows to the class for that code, and a misspelled code doesn't compile), isinstance and err.code in Python, and wakeshift.IsCode(err, wakeshift.CodeTimeout) in Go.

try {
  await notification.emit({}, payload, { to: members, id: messageId })
} catch (err) {
  if (isWakeshiftError(err, "rate_limited")) return retryLater(messageId)
  throw err
}

Canceling a request is never a Wakeshift error: TypeScript rethrows your AbortSignal's reason unchanged, Python raises CancelledError, and Go returns an error that errors.Is(err, context.Canceled) (or context.DeadlineExceeded) matches.

Caught before sending

The SDK checks these itself and throws a UsageError without asking Wakeshift.

config

A bad option or value when you create the client, define an event or attach: an option the SDK doesn't know (builtinTools: { subcribe: false }), a malformed key, a core that isn't https:// (except localhost, 127.0.0.1 and ::1), public with personal or authorize, a second attach on the same server, or a tool registered with a built-in tool's name or a schema that names Wakeshift's arguments. Fix: the option or value the message names.

disabled

A call that needs Wakeshift's answer (createPublishUrl, status, statusOf, end, forgetUser) on a client without a key. Emits and subscribes on a disabled client do nothing instead of throwing. Fix: set WAKESHIFT_KEY, or check wake.enabled (Go wake.Enabled()) before the call.

undeclared_subscribe

A tool subscribed to an event it doesn't name in subscribes. Fix: add the event to the tool's subscribes (Go wakeshift.Subscribes(…)).

no_call

wake.currentCall() outside a tool call that subscribes, or Go's Subscribe with a nil call. Never on a disabled client. Fix: call it inside the handler of a tool you registered through the attachment or named in wrap, or pass the request's context: wake.currentCall(ctx).

call_ended

A call.subscribe, call.unsubscribe or call.resolveSession after the tool's handler returned. Fix: await each one before the handler returns.

identify_failed

Your identify threw, failed or took over 10 seconds (logged as identify_error). call.subscribe throws it (Python raises it, Go returns it); the built-in tools answer isError and native requests are refused instead, with a neutral line for the agent (the details go to your logs, never to the agent). Your tool's own code still runs. Fix: make identify return within 10 seconds, return no user for a credential it can't verify, and throw only when the upstream can't answer. When only your upstream API can verify the credential, see identify through your upstream API.

user_required

requireUser (Python require_user, Go RequireUser) is on and identify returned no user, so Wakeshift refused its part of the request; the log line has the same code. call.subscribe throws it (Python raises it, Go returns it); the built-in tools answer isError and native requests are refused instead, with a line for the agent asking it to sign in. Your tool's own code still runs. Fix: nothing, if anonymous callers are meant to be refused (catch it where your tool also serves them); otherwise check that the caller signed in and that identify finds their user.

From Wakeshift

Wakeshift answered with an error: an APIError. A few are also caught before sending, with the same code, so the code doesn't depend on which side caught it.

bad_request

Something in the request is invalid; the message says what. Also, before sending, more than 1,000 subscriptions in one statusOf, or one without its user. Fix: check the call against the reference.

bad_arguments

An event's arguments or payload don't match its schemas (a UsageError with issues before sending, an APIError from Wakeshift); a routing value that isn't a-z 0-9 . _ -; recipients that don't fit the event: a personal event's emit, publish URL or status without to, or a shared event's with one; or a replay that isn't over 0 and at most 24 hours. Fix: pass arguments and a payload that match the event's schemas. To route on a case-sensitive ID, encode it.

bad_payload

A post to a publish URL whose body isn't a JSON object that matches the event's payload. Fix: send a payload that matches the payload schema.

unknown_event

Your app offers no event by that name, or call.subscribe was given another client's event. An emit gets it only after the SDK has sent your events and tried again. Fix: define the event in this app with defineEvent; the SDK sends your events itself.

unknown_session

The session_key isn't a session Wakeshift knows. Fix: use the session_key from this conversation's own results.

unknown_conversation

The conversation the call names isn't one Wakeshift knows. Fix: use the session_key from this conversation's own results.

other_client

The session_key is a conversation in another MCP client of the same user. Fix: only the client that made a subscription can change it; call again without the key.

private_topic

A subscription to a topic this app and caller may not read. Fix: subscribe only to topics this app and caller may read.

subscription_limit

A user's 21st live webhook subscription (events/subscribe) to your app at once (a once subscription stops counting when it delivers). Renewing one is never refused; the client gets ResourceExhausted, InvalidParams for ChatGPT. Fix: end subscriptions that are no longer needed.

subscription_stopped

The person stopped this subscription. Fix: subscribe again only if they ask.

id_reused

An emit's id was used within the last day for a different emit (another event, arguments, recipients or payload). Nothing was sent. It's an IdReusedError. Fix: use a new id for a different emit; reuse an id only to retry the same emit.

rate_limited

Your emits to lists named over 10,000 recipients in a minute. Fix: slow down, and retry after the Retry-After interval.

too_large

A request over Wakeshift's limits: an emit's text over 1000 bytes is trimmed, not refused, but a payload over 64 KB, or a request body over 512 KB, is refused. Fix: keep text under 1000 bytes and the payload under 64 KB.

unauthenticated

Wakeshift refused your app's key: it was revoked, or it belongs to another console. Every call fails this way until it's fixed, and the SDK logs key_refused. Fix: check WAKESHIFT_KEY, and WAKESHIFT_CORE if your key came from another console.

waitlisted

The key isn't an app's yet: the person who opened wakeshift-cli init's link signed in while Wakeshift's sign-ups were at their cap, so they're on the waitlist and the app wasn't created. init exits 3 with it. Fix: wait for the email saying their account is ready, then run init again: it keeps the key in .env and prints the link again.

no_grant

An agent your app acts for has no grant, or the user revoked it. Fix: ask the user to grant your app access first.

unknown_workspace

The workspace isn't one of your app's, or it was forgotten. Fix: use a workspace ID from wake.workspace.

unknown_publish_url

The publish URL ID isn't one of your app's. Fix: create a new publish URL: this one was revoked or never existed.

bad_signing_secret

A publish URL's signing secret isn't whsec_ and the base64 of 24 to 64 bytes. Fix: pass the sender's Standard Webhooks secret.

unsupported

This Wakeshift doesn't support an option the call used. Fix: upgrade the SDK, or leave the option out.

internal

Wakeshift failed. Fix: retry later; if it persists, contact Wakeshift with the request ID.

bad_response

The answer wasn't Wakeshift's. Fix: check that WAKESHIFT_CORE, or the core option, is the address of the console your key came from.

callback_failed

A webhook URL a native client gave events/subscribe didn't pass Wakeshift's verification, which runs before anything is delivered there. Wakeshift POSTs {"type": "verification", "challenge": "<random>"}, signed like every delivery (Standard Webhooks headers webhook-id, webhook-timestamp and webhook-signature, with the subscription's secret), and the URL must answer with a 2xx whose JSON body echoes the challenge: {"challenge": "<the same value>"}. A 2xx without the echo fails (challenge_failed), as do a redirect (never followed), any other status, no answer within 10 seconds, and an address that isn't public. The secret is the one events/subscribe sent as delivery.secret: whsec_ and the base64 of 24 to 64 bytes. Fix: answer the verification POST with the challenge it carries.

No answer

An APIConnectionError (Go: an *APIError with Status 0). The SDK retries a refused or failed connection itself before throwing.

unreachable

No answer at all: a wrong core address or a network problem. The message names the core it tried. Fix: check that WAKESHIFT_CORE, or the core option, is the address of the console your key came from.

timeout

The SDK's own timeout passed (default 20 seconds). The outcome is unknown: the emit may have gone. Fix: retry with the same id, which emits once.

What MCP Events clients get

When your server refuses a client that subscribes natively (events/list, events/subscribe, events/poll), the SDK answers with an MCP Events error. ChatGPT (client name or User-Agent starting openai-mcp) gets its own codes; every other client gets the MCP Events draft's. Tests that assert a code should match the client they play.

In a webhook receiver

When your own handler receives a webhook and emits, answer the sender by what the emit did:

Log codes

Problems that don't fail a call are logged, never thrown. A Wakeshift failure never changes your tool's result: when Wakeshift's addition to a result can't be had, the agent gets the result exactly as your tool gave it, never an error and never a request to call again, and the SDK logs block_failed. Every line carries one of these codes, and never a key, a session key, a token, a header, a payload, tool arguments or your own error messages. Misuse logs once per client; failures that can go on (a refused key, a broken identify) log at most once per five minutes per code, with a count. Where each SDK logs, and how to silence it, is on its page under "Logging and secrets".