Errors

Problem details

Every error from the API is a problem details object (RFC 9457), sent as application/problem+json with the HTTP status:

{
  "type": "https://agents.chesly.app/docs/errors#rate_limited",
  "title": "Too many requests.",
  "status": 429,
  "detail": "This API key made more than 600 requests in one minute. Retry in 4 s.",
  "code": "rate_limited",
  "request_id": "571d003e-ad60-4a08-858a-b7b5353f39db",
  "retry_after": 4
}

• type links to the code's section on this page.
• title is fixed for each of the API's codes, and detail explains this occurrence.
• code never changes: branch on it, never on title or detail.
• request_id is the request's X-Request-ID. Include it when you write to us.
• retry_after, in seconds, comes with most 429 and 503 answers, along with a Retry-After header.
• A 400 invalid_request also lists each problem in errors, with a JSON Pointer to it.

The MCP server refuses a tool call with the same codes, as a tool error whose text starts with the code: chat_not_found: …. The CLI prints the API's problem as it came, and exits with the code each section names. Its own errors come in the same shape; they're under CLI errors.

400 Bad request

idempotency_key_invalid

400 · The Idempotency-Key header is not valid. · CLI exit code 1

Use 1 to 255 characters from A-Za-z0-9._:-, such as a UUID. The quoted form "…" works too.

invalid_cursor

400 · The cursor is not valid. · CLI exit code 1

Pass next_cursor from the page before, exactly as it came, with the same filters. A cursor of GET /v1/messages?since= expires 15 minutes after its first page: start again without one.

invalid_reply_to

400 · reply_to must be a message in this chat. · CLI exit code 1

reply_to must be the ID of a message in the same chat. Leave it out to send a plain message.

invalid_request

400 · The request is not valid. · CLI exit code 2

A parameter or the body is missing, unknown or out of range. detail names the first problem, and errors lists each one with a JSON Pointer to it. Sending the same request again fails the same way.

invalid_webhook_url

400 · This webhook URL can't be used. · CLI exit code 1

A webhook URL must be a public https:// address of at most 2,048 characters, with no user name or password, whose host doesn't resolve to a private, loopback or link-local address.

media_too_large

400 · The media is too large. · CLI exit code 1

The API serves and takes files of up to 50 MB (50,000,000 bytes), one per message, and the CLI refuses a bigger one before uploading it. Open a bigger file in the Chesly app.

not_a_voice_note

400 · This message is not a voice note. · CLI exit code 1

Only voice notes can be transcribed, and a voice note's type is audio.

text_too_long

400 · The text is too long for this network. · CLI exit code 1

Each network takes text up to its own length, in UTF-16 code units: Instagram 1,000, Discord 2,000, Telegram 4,096, email 100,000 and every other network 10,000. Split the text into several messages.

unsupported_chat

400 · Chesly can't send to this chat. · CLI exit code 1

This chat can't take a message from the API, and detail says why. Answer it in the Chesly app instead.

webhook_limit_reached

400 · This account has the most webhooks allowed. · CLI exit code 1

Your plan's webhooks are used: 25 on Personal, 100 on Pro. Delete one you don't use, send several event types to one URL, or switch to Pro.

401 Unauthorized

invalid_api_key

401 · The API key is missing or not valid. · CLI exit code 3

Send Authorization: Bearer ck_live_… with a key that is still active. A revoked key fails from its next request: make a new one with chesly login or in the dashboard.

402 Payment required

api_plan_required

402 · An API plan is required. · CLI exit code 6

Calls need an API plan. Start the 7-day trial at web.chesly.app/api; GET /v1/me answers without one. The CLI exits with 6.

transcription_limit_reached

402 · This period's transcription minutes are used up. · CLI exit code 6

This month's transcription minutes are used: 600 on Personal, 3,000 on Pro. Transcripts work again when the next month starts, and everything else keeps working. Switch to Pro at web.chesly.app/api for more.

403 Forbidden

forbidden

403 · This request is not allowed. · CLI exit code 1

Something other than the key's scope refused the request, and the same request will be refused again: an API key turning back on a webhook that a leaked key's revoke turned off, say, which only the dashboard can do. Write to us with the request_id if you think it should work.

insufficient_scope

403 · This API key does not allow this request. · CLI exit code 1

A read-only key can only make GET requests. Sending, marking chats read, transcribing and changing webhooks need a full-access key.

signing_key_missing

403 · The account signing key is missing. · CLI exit code 1

Your account's signing key has to be restored before Chesly can read your chats. Open the Chesly app and sign in again, then retry.

404 Not found

account_not_found

404 · Account not found. · CLI exit code 4

None of your connected accounts has this ID. GET /v1/accounts lists them.

chat_not_found

404 · Chat not found. · CLI exit code 4

None of your chats has this ID: chat IDs belong to one user, so take one from GET /v1/chats. The CLI raises it too, when a chat name matches nothing; chesly chats lists the names.

key_not_found

404 · API key not found. · CLI exit code 4

None of your API keys has this ID. GET /v1/keys lists them.

media_not_found

404 · Media not found. · CLI exit code 4

No media has this ID. Use a message's media.id as it came.

message_not_found

404 · Message not found. · CLI exit code 4

No message of yours has this ID. Use message IDs as the API gave them, in answers and events.

not_found

404 · Not found. · CLI exit code 4

No endpoint matches this method and path. IDs go in the path, filters in the query.

webhook_not_found

404 · Webhook not found. · CLI exit code 4

None of your webhooks has this ID. GET /v1/webhooks lists them.

408 Request timeout

upload_timeout

408 · The upload took too long to arrive. · CLI exit code 5

The file didn't arrive in time: an upload has 60 seconds, and must keep up 50 KB a second once its first 10 are over. Your next upload can start in 60 seconds; send it again over a faster connection.

409 Conflict

account_reconnect_required

409 · This account needs to be reconnected. · CLI exit code 1

This account was disconnected on its network. Reconnect it in the Chesly app, then retry.

already_subscribed

409 · You already have an API plan. · CLI exit code 1

You already have an API plan. Manage it at web.chesly.app/api.

idempotency_in_progress

409 · A request with this Idempotency-Key is still running. · CLI exit code 5

The first request with this Idempotency-Key hasn't finished. Wait for Retry-After (1 second), then send the same request with the same key: you get its answer once it's done.

message_request

409 · This chat is a message request. · CLI exit code 1

The API reads message requests but never answers them, because a reply would accept the request on the network. Accept it in the network's own app first.

plan_change_in_progress

409 · A change to your plan is already under way. · CLI exit code 1

Another request is changing your plan right now, such as a second click on Keep plan in the dashboard. Wait a second and look again: the change is usually done.

terms_changed

409 · The API Terms changed. · CLI exit code 1

The API Terms changed since you opened them. Read and accept the current version, then try again.

410 Gone

events_expired

410 · These events are no longer kept. · CLI exit code 1

Events are kept for 7 days on Personal and 30 on Pro, and this after or Last-Event-ID is older. Start again without one, and catch up on what you missed with GET /v1/catch_up. chesly watch does this by itself, with an events_expired warning.

media_expired

410 · The media has expired. · CLI exit code 1

The file is no longer stored, and asking again won't bring it back.

413 Payload too large

payload_too_large

413 · The request body is too large. · CLI exit code 1

The request body is over its limit: 10 MB for a request, 1 MB for an MCP message and 4 KB for chesly login's calls. Send a file to POST /v1/media instead, up to 50 MB (50,000,000 bytes).

422 Unprocessable content

idempotency_key_reused

422 · This Idempotency-Key was used for a different request. · CLI exit code 1

This Idempotency-Key went with another method, path or body in the last 24 hours. Use a new key for a new request; reuse a key only to retry the same request.

transcription_failed

422 · This voice message could not be transcribed. · CLI exit code 1

This voice note's audio can't be transcribed: it may be damaged, or in a format the transcription doesn't read. Asking again gets the same answer.

429 Too many requests

rate_limited

429 · Too many requests. · CLI exit code 5

A key, all of your keys together, an account or the API as a whole went over a limit: the limits list them. Wait Retry-After seconds (also in retry_after), then retry. GET /v1/me shows your limits.

send_limit_reached

429 · This account's send limit is reached. · CLI exit code 5

This connected account reached its send limit: 60 an hour and 250 a day on WhatsApp, 30 an hour and 150 a day on every other network. Wait Retry-After seconds. GET /v1/me shows where each account stands.

too_many_streams

429 · Too many open event streams. · CLI exit code 5

You can keep 10 event streams open at once on Personal and 25 on Pro. Close one, or poll GET /v1/events instead.

500 Internal server error

internal_error

500 · Something went wrong on our side. · CLI exit code 1

Something failed on Chesly's side, logged under the request_id. Retry later, and if it keeps happening, write to us with the request_id. The CLI raises it too, for a failure it didn't expect.

502 Bad gateway

email_send_failed

502 · The email provider refused the message. · CLI exit code 5

Your email provider refused the message. Check the account in the Chesly app, then retry.

503 Service unavailable

api_paused

503 · The Chesly API is paused. · CLI exit code 5

Chesly has paused the API for a moment. Retry after retry_after seconds.

feed_unavailable

503 · The feed is temporarily unavailable. · CLI exit code 5

The since feed can't page right now. Retry in a moment, or ask for a stretch of time that fits one page.

media_unavailable

503 · The media is temporarily unavailable. · CLI exit code 5

The file couldn't be fetched just now. Retry after retry_after seconds when it's there, or in a moment.

network_unavailable

503 · This network is temporarily unavailable. · CLI exit code 5

Chesly has paused sending and marking read on this network to protect your accounts. Reads still work. Retry later, or do it in the network's own app.

plan_unavailable

503 · Your API plan can't be checked just now. · CLI exit code 5

Chesly couldn't read your plan just now, so it makes nothing your plan limits: a new key or a new webhook. Everything else goes on. Retry after retry_after seconds, about 5; chesly login keeps polling by itself.

search_unavailable

503 · Search is temporarily unavailable. · CLI exit code 5

Search can't answer right now. Retry in a moment; reading chats and catching up still work.

transcription_unavailable

503 · Transcription is temporarily unavailable. · CLI exit code 5

Transcription can't answer right now. Retry in a moment.

upstream_unavailable

503 · Your messages are temporarily unavailable. · CLI exit code 5

Chesly couldn't reach your messages just now. Retry after retry_after seconds, about 5.

CLI errors

The CLI raises these itself, in the same shape, with a type on this page and a code that never changes. Its problems carry their message as title, so branch on code; the titles below describe each code. In JSON mode it prints them to standard error as one line, and it exits with one of these codes:

When something in front of the API answers without problem details, such as the gateway during a Chesly deploy, the CLI names the error after the HTTP status: http_400, http_404, http_413, http_429, http_500, http_502, http_503 or http_504, and http_error for any other status.

access_denied

CLI · The sign-in was denied.

Someone chose Deny on the approval page, so nothing was stored. Run chesly login again.

ambiguous_chat

CLI · The chat name matches more than one chat.

The error lists the chats that match as candidates. Use one of their chat IDs instead of the name.

credentials_file_error

CLI · The credentials file couldn't be read or written.

chesly logout couldn't remove ~/.config/chesly/credentials.json. Check the file's permissions, or delete it yourself.

delivery_failed

CLI · The network did not take the message.

chesly send --wait saw the network refuse the message for certain (delivery.error.certain is true), and the error says why. Fix what it names before you send again. The CLI exits with 1.

delivery_unconfirmed

CLI · The network didn't confirm the message, so it may have been delivered.

chesly send --wait saw the send fail without the network confirming it (certain: false: a timeout, or an unknown error), so the message may have been delivered. Check the chat before you send it again. The CLI exits with 5.

expired_token

CLI · The sign-in code expired.

A sign-in link lasts 10 minutes. Run chesly login again and approve the new link.

file_unreadable

CLI · The file can't be read.

The CLI can't read the file --file names. Check its path and its permissions.

http_400

CLI · HTTP 400 · Bad Request, without details.

Something in front of the API refused the request without details. Check CHESLY_API_URL if you set it, then retry.

http_404

CLI · HTTP 404 · Not Found, without details.

The request reached something other than the API, which answered 404 without details. Check CHESLY_API_URL if you set it.

http_413

CLI · HTTP 413 · Payload Too Large, without details.

Something in front of the API found the request too large. A file can be up to 50 MB (50,000,000 bytes).

http_429

CLI · HTTP 429 · Too Many Requests, without details.

Too many requests, answered without details, as the sign-in's own limit does. Wait a minute, then retry.

http_500

CLI · HTTP 500 · Internal Server Error, without details.

A server error without details. Retry in a moment, and if it keeps happening, write to us.

http_502

CLI · HTTP 502 · Bad Gateway, without details.

The gateway in front of the API got no answer from it, as happens for a few seconds during a Chesly deploy. Retry in a few seconds.

http_503

CLI · HTTP 503 · Service Unavailable, without details.

The gateway in front of the API answered that it is unavailable. Retry in a few seconds.

http_504

CLI · HTTP 504 · Gateway Timeout, without details.

The gateway in front of the API gave up waiting for it. Retry in a few seconds.

http_error

CLI · An HTTP error without details.

An HTTP error without details, with a status the codes above don't name: status says which. Check CHESLY_API_URL if you set it, then retry later.

invalid_api_url

CLI · CHESLY_API_URL is not a usable API URL.

CHESLY_API_URL must be an http:// or https:// URL, such as https://api.chesly.app. Fix it, or unset it to use Chesly's.

invalid_key_format

CLI · The API key is not well formed.

A key is ck_live_ and 48 letters, digits, _ or -. Check CHESLY_API_KEY, the stored key or the key you gave chesly login --key -, or run chesly login again. A malformed CHESLY_API_KEY or stored key exits with 3, and one given to --key - with 2.

invalid_response

CLI · The API's answer is not what the CLI expects.

Something other than the Chesly API answered, such as a proxy or a wrong CHESLY_API_URL. Check the URL, then retry.

keychain_error

CLI · The OS keychain refused.

The OS keychain refused to read or change the key. Unlock it, or set CHESLY_API_KEY instead.

keychain_timeout

CLI · The OS keychain didn't answer in time.

The keychain didn't answer within 10 seconds: it may be locked, or waiting for someone to answer a dialog. Unlock it or answer the dialog, then retry, or set CHESLY_API_KEY.

login_not_started

CLI · No sign-in is waiting to finish.

chesly login --wait found no sign-in waiting to finish. Run chesly login --no-wait first, then chesly login --wait within 10 minutes.

network_error

CLI · The CLI couldn't reach the API.

The request got no answer: no connection, a DNS failure or a timeout. Check your connection, and CHESLY_API_URL if you set it, then retry.

not_signed_in

CLI · Not signed in.

Run chesly login, or set CHESLY_API_KEY. The CLI exits with 3.

usage_error

CLI · The command is not valid.

An argument is missing or an option is unknown. Run the command with --help. The CLI exits with 2.

CLI warnings

The CLI prints a warning on standard error and goes on: a warning never changes the exit code. In JSON mode each is one line, {"warning": "<code>", "message": "…"}.

delivery_wait_failed

Warning · The message was sent, but following its delivery failed.

The message went out, but following its delivery failed: a 401 or a 402 on a check, say. The command still exits with 0, and the warning carries the idempotency_key that asks the API for its answer again.

env_key_set

Warning · CHESLY_API_KEY wins over the key login stored.

CHESLY_API_KEY is set, so the CLI uses it rather than the key chesly login stored. Unset it to use the stored key.

event_too_large

Warning · An event too large to read was skipped.

An event too large to read ended the stream twice in a row, so chesly watch went on after it. The warning names its ID.

events_expired

Warning · The resume point is no longer kept, so watching starts from now.

chesly watch was asked to resume from a point older than your plan keeps events (7 days on Personal, 30 on Pro), so it starts from new events. chesly catchup shows what you missed.

invalid_event

Warning · An event the CLI could not read was skipped.

chesly watch skipped an event it couldn't read, and goes on.

key_details_unavailable

Warning · The new key's details didn't load.

chesly login stored the new key, but its details didn't load, so key is null. chesly whoami shows them.

key_still_active

Warning · A key this CLI no longer uses is still active.

A key this CLI no longer uses still works. The warning names it by its ID, first 12 and last 4 characters: revoke it with chesly keys revoke <key_id>, or in the dashboard.

reconnecting

Warning · The event stream dropped and is reconnecting.

The event stream dropped. chesly watch reconnects by itself, after 3 seconds and then longer, up to 30, and resumes after the last event it had.