Errors
A refused tool call comes back as a normal result with isError set, a code and a hint, so the assistant can fix its next call on its own.
VALIDATION_FAILED
Status: 400
What it means: An input failed its schema. The details list each field.
API_SUBSCRIPTION_REQUIRED
Status: 402
What it means: This action needs an active WhatsApp API plan.
PLAN_LIMIT_REACHED
Status: 402
What it means: The monthly message allowance or a plan cap is used up, or the plan does not include MCP (API Lite). Upgrade to API Growth or API Max.
FORBIDDEN
Status: 403
What it means: The person this key belongs to is not an owner or admin, and the action needs one.
INBOX_SEAT_REQUIRED
Status: 402
What it means: The person this key belongs to has no inbox seat on the plan.
OPT_IN_DASHBOARD_ONLY
Status: 403
What it means: Opting a contact back in is done by a person in the dashboard.
NOT_FOUND, CONTACT_NOT_FOUND, …
Status: 404
What it means: Nothing with that id exists in this workspace.
PHONE_DUPLICATE
Status: 409
What it means: That number is already a contact.
DUPLICATE_RULE
Status: 409
What it means: Another auto reply already answers that word.
WINDOW_CLOSED
Status: 409
What it means: Free text is only allowed within 24 hours of the customer's last message. Use a template.
NO_CONNECTION
Status: 409
What it means: No WhatsApp number is connected.
| Code | Status | What it means |
|---|---|---|
| VALIDATION_FAILED | 400 | An input failed its schema. The details list each field. |
| API_SUBSCRIPTION_REQUIRED | 402 | This action needs an active WhatsApp API plan. |
| PLAN_LIMIT_REACHED | 402 | The monthly message allowance or a plan cap is used up, or the plan does not include MCP (API Lite). Upgrade to API Growth or API Max. |
| FORBIDDEN | 403 | The person this key belongs to is not an owner or admin, and the action needs one. |
| INBOX_SEAT_REQUIRED | 402 | The person this key belongs to has no inbox seat on the plan. |
| OPT_IN_DASHBOARD_ONLY | 403 | Opting a contact back in is done by a person in the dashboard. |
| NOT_FOUND, CONTACT_NOT_FOUND, … | 404 | Nothing with that id exists in this workspace. |
| PHONE_DUPLICATE | 409 | That number is already a contact. |
| DUPLICATE_RULE | 409 | Another auto reply already answers that word. |
| WINDOW_CLOSED | 409 | Free text is only allowed within 24 hours of the customer's last message. Use a template. |
| NO_CONNECTION | 409 | No WhatsApp number is connected. |