# MCP server — Errors


Source: https://vertexsms.com/en/mcp/errors

Every MCP tool that fails returns a uniform error envelope. The shape is identical regardless of which tool fired or whether the failure was local validation, an upstream API error, or a transient outage.

## Envelope

```json
{
  "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
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| code | string | Stable machine-readable code (see 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. |

## 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 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 (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 the REST API, so existing client code that handles `error_uri` / `retryable` already works.