Every MCP tool that fails returns a uniform error envelope. The shape is the same regardless of which tool fired or whether the failure was local validation, an upstream API error, or a transient outage.
Envelope
ERROR ENVELOPE
{
"error": {
"code": "AUTH_INVALID",
"message": "VertexSMS rejected the provided token.",
"retryable": false,
"signup_url": "https://vertexsms.com/en/contact",
"signin_url": "https://vertexsms.com/en/login",
"token_url": "https://tool.vertexsms.com/settings/api",
"vertex_error_code": null
}
}
Envelope fields
| Field | Type | Description |
|---|---|---|
| code | string | Stable machine-readable code. See the catalog below. |
| message | string | Human-readable description suitable for showing to the end user. |
| retryable | bool | Whether the same call may succeed if retried later. Transient failures are retryable; auth or input errors are not. |
| signup_url | string | Present on auth errors. Where a user without an account should request access. |
| signin_url | string | Present on auth errors. Where an existing user should sign in to refresh their token. |
| token_url | string | Present on auth errors. The dashboard page for managing API tokens. |
| vertex_error_code | int|null | The numeric error code surfaced by the underlying VertexSMS REST API, if any. REST API error codes apply. |
Error codes
| Code | Retryable | When it fires & how to recover |
|---|---|---|
AUTH_REQUIRED | no | No Authorization header was present. The WWW-Authenticate response header includes a resource_metadata=... URL that OAuth-capable clients can use to start a fresh consent flow. Manual recovery: paste a token via your client's MCP config. |
AUTH_INVALID | no | Token was rejected by VertexSMS, expired, revoked, IP-restricted, or scope-restricted. Recover by signing in to the dashboard, regenerating the token, and updating your client config. OAuth clients should re-trigger the consent flow. |
RATE_LIMITED | yes | Per-IP rate limit on unauthenticated requests was exceeded (typically 20 / minute). Authenticated requests are not rate-limited at the MCP layer. Recover by waiting; honor the Retry-After header. |
INVALID_INPUT | no | Tool arguments failed schema validation locally before any upstream call. Read message for the specific field; fix and resubmit. |
VERTEX_SEND_FAILED | no | VertexSMS rejected the request with a 4xx status (other than 401/403). Common reasons: malformed phone number, sender not approved for the destination country, blacklisted destination. vertex_error_code often disambiguates, cross-reference with REST API errors. |
VERTEX_UNAVAILABLE | yes | Network failure or 5xx from VertexSMS. Wait a few seconds and retry. If it persists, contact support. |
RATES_UNAVAILABLE | yes | Specific to get_sms_rates when the rate cache cannot be refreshed. Treat as transient. |
NOT_FOUND | no | Returned when an entity referenced by the tool call (operator ID, sender ID) does not exist on the underlying account. |
The error envelope is intentionally identical to the one used by our REST API, so existing client code that handles error_uri / retryable already works.