Error codes
Every error has code, error, error_category and doc_url. Act on the category; the code says exactly what happened.
Rate limited rate_limited
Wait retry_after_seconds, then try again. Nothing was sent.
| Code | What it means | What to do |
|---|---|---|
RATE_LIMITED429 | Over a pace limit for this action on this account. Nothing was sent. | Wait retry_after_seconds, then try again. Do not work around it. |
DAILY_CAP429 | The account used all of today's allowance for this action. | Try again after retry_after_seconds, usually tomorrow. |
Allowance used up quota_exhausted
A plan, spend or daily allowance is used up. Tell the owner.
| Code | What it means | What to do |
|---|---|---|
PLAN_LIMIT_REACHED402 | The Free plan allows 1 account and 600 actions a month (20 a day). | Ask the owner to move to Pay as you go (upgrade_url). Reads keep working. |
SPEND_CAP_REACHED402 | Usage reached the monthly limit the owner set. | Ask the owner to raise the limit or wait for the new month. |
BILLING_REQUIRED402 | The workspace needs billing before this can run. | Ask the owner to add a card or start a plan. |
MONTHLY_CAP_REACHED402 | A monthly allowance is used up. | Wait for the new month or ask the owner to raise it. |
Invalid input invalid_input
Fix the request and send it again.
| Code | What it means | What to do |
|---|---|---|
INVALID_INPUT400 | A field is missing or not in the right form. | Read error, fix the field and send again. |
DISPOSABLE_EMAIL400 | The email is a temporary or throwaway inbox. Spaces needs a work or personal email. | Ask the person for their work or personal email and start sign-up again with it. |
INVALID_WORKFLOW400 | The workflow graph does not pass the checks. | Fix each item in problems and send again. |
INVALID_URL400 | The link is not a public https address. | Send a public https link. |
PAYLOAD_TOO_LARGE413 | The request or its media is too big. | Send smaller files or fewer at once. |
CONFIRM_REQUIRED400 | This step needs confirm: true. | Ask the person first, then send confirm: true. |
OWNER_CONFIRMATION_REQUIRED400 | The workspace owner has to agree first. | Ask the owner, then send owner_confirmed: true. |
HANDLE_REQUIRED409 | Spaces does not know the account's number, username or Page yet, so it cannot build the chat link. | Ask the owner for it and pass it as handle. |
Permission permission
The key, the person’s role or the account does not allow it.
| Code | What it means | What to do |
|---|---|---|
MISSING_SCOPE403 | The key does not have the permission this call needs. | Ask the owner to give the AI agent that permission in Spaces. |
FORBIDDEN403 | This key or person may not do this. | Ask the owner. |
FORBIDDEN_ROLE403 | The person who made the key does not have the role for this. | Ask the workspace owner. |
PERMISSION_REQUIRED403 | The account did not give the permission this needs. | Reconnect the account and accept every permission. |
UNAUTHENTICATED401 | No valid API key or sign-in. | Send the API key as a Bearer token. |
KEY_SUSPENDED403 | This key is paused or suspended. | Ask the owner to resume it. |
AGENT_PAUSED409 | The owner paused this AI agent or all sending. | Wait until the owner resumes it. |
ACCOUNT_NOT_CONNECTED409 | The account is signed out or not working. | Ask the owner to reconnect it (create_messaging_connect_link with account_id). |
CHANNEL_DISABLED403 | This channel is not available for the workspace. | Use another channel, or ask the owner. |
CONSENT_REQUIRED403 | The person has not agreed to get messages (WhatsApp opt-in). | Only message people who wrote first or opted in. |
Not found not_found
It does not exist, or this key cannot see it.
| Code | What it means | What to do |
|---|---|---|
NOT_FOUND404 | No such thing in this workspace, or this key cannot see it. | Check the id with the list tool. |
NOT_ENABLED503 | This feature is not switched on yet. | Use another tool, or ask the owner. |
Platform rejected platform_rejected
The platform refused it. Change the request or skip it.
| Code | What it means | What to do |
|---|---|---|
NOT_SUPPORTED422 | The platform does not support this. | Use another channel or tool. |
NOT_SUPPORTED_ON_OFFICIAL422 | Not possible on the account's official connection. | Connect the account with full access, or skip it. |
ACCOUNT_RESTRICTED423 | The platform restricted the account. | Stop and tell the owner. Let the account rest. |
PLATFORM_REJECTED422 | The platform refused this request. | Read error for the reason, change the request, or skip it. |
Conflict conflict
It clashes with the current state. Read it again first.
| Code | What it means | What to do |
|---|---|---|
IN_PROGRESS409 | The same request is still running. | Ask again in a minute with the same idempotency key. |
HANDED_OVER409 | A person on the team took over this chat. | Do not write there until it is handed back. |
NOT_HANDED_OVER409 | The chat is not handed to a person. | Nothing to hand back. |
OUTSIDE_WORKING_HOURS409 | Outside the working hours set for this send. | Send later, inside the hours. |
OUTSIDE_24H_WINDOW409 | The platform only allows a reply within 24 hours of the person's last message. | Wait for the person to write again. |
IDEMPOTENCY_CONFLICT409 | This idempotency key was used for a different request. | Use a new key for a new request. |
NEEDS_REVIEW409 | The send is waiting for a check. | Wait, or ask the owner. |
CONFLICT409 | It clashes with the current state. | Read the current state and try again. |
NOT_PENDING409 | It is no longer waiting, so it cannot be changed. | Read it again to see what happened. |
ALREADY_PENDING409 | The same thing is already waiting. | Wait for it to finish. |
CHAT_DESTINATION_INVALID409 | The connected account cannot be the chat of this ad: the WhatsApp number is not linked to the Page or the business, the Instagram account is not linked to the Page, or the Messenger account is another Page. | Read error for what to link in Meta, or pick another account or Page. Nothing was created. |
Internal internal
Something went wrong on our side. Try again.
| Code | What it means | What to do |
|---|---|---|
INTERNAL500 | Something went wrong on our side. | Try again. If it keeps happening, send_feedback with the request id. |
Limits are explained in full on the limits page. What each message looks like on a channel: errors by channel.