Spaces

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.

CodeWhat it meansWhat to do
RATE_LIMITED
429
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_CAP
429
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.

CodeWhat it meansWhat to do
PLAN_LIMIT_REACHED
402
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_REACHED
402
Usage reached the monthly limit the owner set.Ask the owner to raise the limit or wait for the new month.
BILLING_REQUIRED
402
The workspace needs billing before this can run.Ask the owner to add a card or start a plan.
MONTHLY_CAP_REACHED
402
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.

CodeWhat it meansWhat to do
INVALID_INPUT
400
A field is missing or not in the right form.Read error, fix the field and send again.
DISPOSABLE_EMAIL
400
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_WORKFLOW
400
The workflow graph does not pass the checks.Fix each item in problems and send again.
INVALID_URL
400
The link is not a public https address.Send a public https link.
PAYLOAD_TOO_LARGE
413
The request or its media is too big.Send smaller files or fewer at once.
CONFIRM_REQUIRED
400
This step needs confirm: true.Ask the person first, then send confirm: true.
OWNER_CONFIRMATION_REQUIRED
400
The workspace owner has to agree first.Ask the owner, then send owner_confirmed: true.
HANDLE_REQUIRED
409
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.

CodeWhat it meansWhat to do
MISSING_SCOPE
403
The key does not have the permission this call needs.Ask the owner to give the AI agent that permission in Spaces.
FORBIDDEN
403
This key or person may not do this.Ask the owner.
FORBIDDEN_ROLE
403
The person who made the key does not have the role for this.Ask the workspace owner.
PERMISSION_REQUIRED
403
The account did not give the permission this needs.Reconnect the account and accept every permission.
UNAUTHENTICATED
401
No valid API key or sign-in.Send the API key as a Bearer token.
KEY_SUSPENDED
403
This key is paused or suspended.Ask the owner to resume it.
AGENT_PAUSED
409
The owner paused this AI agent or all sending.Wait until the owner resumes it.
ACCOUNT_NOT_CONNECTED
409
The account is signed out or not working.Ask the owner to reconnect it (create_messaging_connect_link with account_id).
CHANNEL_DISABLED
403
This channel is not available for the workspace.Use another channel, or ask the owner.

Not found not_found

It does not exist, or this key cannot see it.

CodeWhat it meansWhat to do
NOT_FOUND
404
No such thing in this workspace, or this key cannot see it.Check the id with the list tool.
NOT_ENABLED
503
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.

CodeWhat it meansWhat to do
NOT_SUPPORTED
422
The platform does not support this.Use another channel or tool.
NOT_SUPPORTED_ON_OFFICIAL
422
Not possible on the account's official connection.Connect the account with full access, or skip it.
ACCOUNT_RESTRICTED
423
The platform restricted the account.Stop and tell the owner. Let the account rest.
PLATFORM_REJECTED
422
The platform refused this request.Read error for the reason, change the request, or skip it.

Platform unavailable provider_unavailable

The platform did not answer. Try again later.

CodeWhat it meansWhat to do
PROVIDER_UNAVAILABLE
502
The platform did not answer.Try again in a few minutes.
OUTCOME_UNKNOWN
502
The platform did not confirm whether it went out.Check the account before you send it again. Do not resend blindly.
NOT_CONFIGURED
503
This platform is not set up on this server.Ask the Spaces team.

Conflict conflict

It clashes with the current state. Read it again first.

CodeWhat it meansWhat to do
IN_PROGRESS
409
The same request is still running.Ask again in a minute with the same idempotency key.
HANDED_OVER
409
A person on the team took over this chat.Do not write there until it is handed back.
NOT_HANDED_OVER
409
The chat is not handed to a person.Nothing to hand back.
OUTSIDE_WORKING_HOURS
409
Outside the working hours set for this send.Send later, inside the hours.
OUTSIDE_24H_WINDOW
409
The platform only allows a reply within 24 hours of the person's last message.Wait for the person to write again.
IDEMPOTENCY_CONFLICT
409
This idempotency key was used for a different request.Use a new key for a new request.
NEEDS_REVIEW
409
The send is waiting for a check.Wait, or ask the owner.
CONFLICT
409
It clashes with the current state.Read the current state and try again.
NOT_PENDING
409
It is no longer waiting, so it cannot be changed.Read it again to see what happened.
ALREADY_PENDING
409
The same thing is already waiting.Wait for it to finish.
CHAT_DESTINATION_INVALID
409
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.

CodeWhat it meansWhat to do
INTERNAL
500
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.