Errors

Sender or provider not ready

Cause: TextTree could not reserve a sender number or the messaging provider rejected the request.

Fix: Confirm the workspace has a connected sender or available instant-pool sender, then retry after provider readiness is restored.

Retry: Retry only after the sender or provider issue is resolved.

Example response:

{
  "error": {
    "code": "branded_number_missing",
    "message": "No connected branded sender is available for this workspace.",
    "fix": "Connect a branded sender or switch to a supported sending mode.",
    "retry": "retry_after_sender_ready"
  }
}

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"
  }
}

Insufficient balance

Cause: The account does not have enough posted prepaid SMS balance for the requested send.

Fix: Create a USDC funding invoice, pay the exact amount, and wait for the invoice status to become paid before retrying.

Retry: Retry after the balance is credited.

Example response:

{
  "error": "insufficient_balance"
}

Amount below minimum

Cause: The funding invoice amount is below the current onboarding or product minimum.

Fix: Submit a larger amount that meets the returned minimum_cents.

Retry: Retry immediately with a valid amount.

Example response:

{
  "error": "amount_below_minimum",
  "minimum_cents": 1000
}

Onchain invoice not found

Cause: The invoice does not exist for the authenticated user or the ID is incorrect.

Fix: Use the invoice ID returned by POST /api/v1/onboarding/funding-invoices or onboarding.create_invoice.

Retry: Retry with a valid invoice ID.

Example response:

{
  "error": "onchain_invoice_not_found"
}

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 TextTree 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 TextTree access token is required."
  }
}