# Errors

Canonical URL: https://texttree.ai/en/docs/errors/
Markdown URL: https://texttree.ai/en/docs/errors.md
Page type: docs
Translation status: approved
Legal status: not_required

## Summary

Common TextTree API and delivery errors with causes, fixes, and retry guidance.

## Source content

## 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:

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

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

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

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

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

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

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

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