Errors

Recipient not verified in test mode

Cause: Test mode can restrict recipient numbers.

Fix: Verify the recipient or switch to live mode after completing compliance.

Retry: Retry after the recipient or environment is valid.

Example response:

{
  "error": {
    "code": "recipient_not_verified",
    "message": "Recipient number is not verified in test mode.",
    "fix": "Verify this recipient number or switch to live mode after compliance approval.",
    "retry": "retry_after_verification"
  }
}

Workspace suppressed

Cause: The recipient phone number has an active workspace-level suppression. This usually comes from a provider STOP/opt-out event or a manual operator suppression.

Fix: Respect the suppression or remove it from Workspace Settings only if your compliance process allows that recipient to receive SMS again.

Retry: Do not retry until the suppression is removed.

Example response:

{
  "error": {
    "code": "workspace_suppressed",
    "message": "Recipient is suppressed for this workspace.",
    "fix": "Remove the workspace suppression only after validating the recipient can receive SMS.",
    "retry": "do_not_retry"
  }
}

Campaign suppressed

Cause: The recipient phone number has an active opt-out for a specific campaign.

Fix: Keep the campaign delivery skipped or remove the campaign opt-out from the Campaign page if it was created in error.

Retry: Do not retry the rendered delivery until the campaign suppression is removed.

Spend limit exceeded

Cause: The workspace spend cap would be exceeded.

Fix: Increase the cap or wait until the next billing period.

Retry: Retry only after spend is available.

Example response:

{
  "error": {
    "code": "spend_limit_exceeded",
    "message": "This message would exceed the workspace spend limit.",
    "fix": "Increase the spend limit or wait until the next billing period.",
    "retry": "retry_after_spend_available"
  }
}

Webhook delivery failed

Cause: Your webhook endpoint returned a non-2xx response or timed out.

Fix: Inspect the delivery response body in the Webhooks page, deploy a fix, then replay the event.

Retry: Replay manually after the endpoint is healthy.

Example delivery record:

{
  "event_id": "evt_123",
  "status": "failed",
  "response_code": 500,
  "latency_ms": 842,
  "next_retry": null
}

Invalid access token

Cause: The Textree bearer token is missing, malformed, expired, revoked, or missing the required scope.

Fix: refresh the browser session, issue a new agent token, or include the missing scope.

Retry: Retry with a valid token.

{
  "error": {
    "code": "unauthorized",
    "message": "A valid Textree access token is required."
  }
}