JSON-RPC error codes, Whats91 MCP error identifiers, and how to react to each.
MCP Errors
Summary
JSON-RPC error codes, Whats91 MCP error identifiers, and how to react to each.
Prerequisites
- A Whats91 account
- A generated public API token
Related documentation
Errors are returned as JSON-RPC error objects. The JSON-RPC code says which layer failed; data.code carries the stable Whats91 identifier, and data.retryable says whether retrying can help.
{
"jsonrpc": "2.0",
"id": 7,
"error": {
"code": -32003,
"message": "The MCP operation rate limit was reached. Wait before retrying.",
"data": {
"code": "MCP_RATE_LIMITED",
"retryable": true
}
}
}JSON-RPC Codes
| Code | Meaning |
|---|---|
| -32602 | Invalid params. Tool arguments failed schema validation. data.code is MCP_INVALID_PARAMS. |
| -32003 | The operation was rejected by Whats91: authorization, entitlement, readiness, or rate limit. |
| -32002 | The requested resource was not found. |
| -32603 | Internal error. data.code is MCP_INTERNAL_ERROR. |
| -32000 | Transport rejection, such as calling GET or DELETE on the MCP endpoint. |
Whats91 Error Codes
| data.code | Retryable | Meaning and action |
|---|---|---|
| MCP_INVALID_PARAMS | No | Arguments failed the tool input schema. Fix the arguments; the message names the offending path. |
| MCP_AUTHENTICATED_TENANT_REQUIRED | No | The grant carries no authenticated Whats91 tenant. Re-run the OAuth flow. |
| MCP_FEATURE_DISABLED | No | The capability is not enabled for the account. |
| MCP_SUBSCRIPTION_REQUIRED | No | An active subscription is required. |
| MCP_SUBSCRIPTION_EXPIRED | No | The subscription has expired. Renew it. |
| MCP_ADDON_ACCESS_REQUIRED | No | The required add-on is not active. |
| MCP_RATE_LIMITED | Yes | A rate-limit window was exhausted. Wait, then retry. |
| MCP_OPERATION_FAILED | No | The operation could not be completed. Generic client-side failure. |
| MCP_INTERNAL_ERROR | No | An internal error occurred. Report the X-Request-ID value to support. |
Warning
Error messages are deliberately non-revealing. Whats91 never leaks internal identifiers, stack traces, provider payloads, or another tenant existence through MCP errors. Use the correlation id for support rather than trying to parse detail out of the message.
Validation Messages
Input validation reports one problem at a time, addressed by path, so a model can correct the specific argument rather than guessing.
| Example message | Cause |
|---|---|
| campaign_uid is required | A required property was missing. |
| setup_uid has an invalid format | The value failed the schema pattern. |
| limit exceeds the maximum | A numeric value was above the allowed maximum. |
| recipients has too many items | An array exceeded maxItems. |
| scheduled_at is not a supported argument | An unknown property was sent; tool schemas reject unknown properties. |
Handling Failures Safely
- Never auto-retry a NO_AUTOMATIC_RETRY tool. Surface the failure for a human decision.
- Retry IDEMPOTENCY_REQUIRED tools only with the original idempotency key.
- For PROVIDER_AWARE failures, read the current state with a read-only tool before deciding whether to retry.
- Treat MCP_RATE_LIMITED as backpressure, not as a failure of the request content.
- Log the X-Request-ID response header on every call so a failed operation can be traced end to end.
Related Documentation
MCP
Connect an AI assistant to Whats91 through the Model Context Protocol and give it safe, scoped access to your WhatsApp workspace.
Connect and Authorize
Register an OAuth 2.1 client, complete the PKCE authorization flow, and obtain a scoped Whats91 MCP access token.
Protocol
The JSON-RPC methods the Whats91 MCP endpoint implements, protocol negotiation, and transport rules.
Scopes
Every Whats91 MCP OAuth scope, what it unlocks, and how to choose a minimal set.