Errors

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": {
    "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

Fieldcode

Typestring

DescriptionStable machine-readable code. See the catalog below.

Fieldmessage

Typestring

DescriptionHuman-readable description suitable for showing to the end user.

Fieldretryable

Typebool

DescriptionWhether the same call may succeed if retried later. Transient failures are retryable; auth or input errors are not.

Fieldsignup_url

Typestring

DescriptionPresent on auth errors. Where a user without an account should request access.

Fieldsignin_url

Typestring

DescriptionPresent on auth errors. Where an existing user should sign in to refresh their token.

Fieldtoken_url

Typestring

DescriptionPresent on auth errors. The dashboard page for managing API tokens.

Fieldvertex_error_code

Typeint|null

DescriptionThe numeric error code surfaced by the underlying VertexSMS REST API, if any. REST API error codes apply.

Error codes

Code catalog

Code

Retryable

When it fires & how to recover

CodeAUTH_REQUIRED

Retryableno

DetailNo 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.

CodeAUTH_INVALID

Retryableno

DetailToken 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.

CodeRATE_LIMITED

Retryableyes

DetailPer-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.

CodeINVALID_INPUT

Retryableno

DetailTool arguments failed schema validation locally before any upstream call. Read message for the specific field; fix and resubmit.

CodeVERTEX_SEND_FAILED

Retryableno

DetailVertexSMS 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.

CodeVERTEX_UNAVAILABLE

Retryableyes

DetailNetwork failure or 5xx from VertexSMS. Wait a few seconds and retry. If it persists, contact support.

CodeRATES_UNAVAILABLE

Retryableyes

DetailSpecific to get_sms_rates when the rate cache cannot be refreshed. Treat as transient.

CodeNOT_FOUND

Retryableno

DetailReturned 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.