# Erros

URL canônica: https://texttree.ai/pt-br/docs/erros/
URL em Markdown: https://texttree.ai/pt-br/docs/erros.md
Tipo de página: docs
Translation status: draft
Legal status: english_controls

## Resumo

API TextTree comum e erros de entrega com causas, soluções e guia de nova tentativa.

## Conteúdo fonte

## Remetente ou fornecedor não está pronto

Causa: TextTree não conseguiu reservar um número de remetente ou o provedor de mensagens rejeitou a solicitação.

Solução: confirme se o espaço de trabalho tem um remetente conectado ou disponível no pool instantâneo e tente novamente após
que a disponibilidade do fornecedor seja restaurada.

Tentar novamente: tente novamente somente depois que o problema do remetente ou provedor for resolvido.

Exemplo de resposta:

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

## Espaço de trabalho excluído

Causa: O número de telefone do destinatário tem uma supressão ativa no nível do espaço de trabalho. Isso geralmente vem
de um evento STOP/opt-out do provedor ou de uma supressão manual pelo operador.

Solução: respeite a exclusão ou remova-a das Configurações do Workspace somente se o seu processo de conformidade
permite que esse destinatário receba SMS novamente.

Tentar novamente: não tente novamente até que a exclusão seja removida.

Exemplo de resposta:

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

## Campanha excluída

Causa: O número de telefone do destinatário tem uma opção de exclusão ativa para uma campanha específica.

Solução: Ignore a entrega da campanha ou cancele a assinatura da campanha na página Campanha se
foi criado por engano.

Tentar novamente: não tente novamente o delivery gerado até que a supressão da campanha seja removida.

## Limite de gastos excedido

Causa: O limite de gastos do espaço de trabalho seria excedido.

Solução: Aumente o limite ou aguarde até o próximo período de faturamento.

Tentar novamente: tente novamente somente quando os gastos estiverem disponíveis.

Exemplo de resposta:

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

## Saldo insuficiente

Causa: A conta não possui saldo pré-pago de SMS suficiente creditado para a entrega solicitada.

Solução: Crie uma fatura de financiamento em USDC, pague o valor exato e aguarde que o status da fatura mude para
`paid` antes de tentar novamente.

Tentar novamente: tente novamente após o saldo ser creditado.

Exemplo de resposta:

```json
{
  "error": "insufficient_balance"
}
```

## Valor abaixo do mínimo

Causa: O valor da fatura de financiamento está abaixo do valor mínimo atual de integração ou do produto.

Solução: Envie um valor maior que atenda ao `minimum_cents` devolvido.

Tentar novamente: tente novamente imediatamente com um valor válido.

Exemplo de resposta:

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

## Fatura Onchain não encontrada

Causa: A fatura não existe para o usuário autenticado ou o ID está incorreto.

Solução: Use o ID da fatura retornado por `POST /api/v1/onboarding/funding-invoices` ou
`onboarding.create_invoice`.

Tentar novamente: tente novamente com um ID de fatura válido.

Exemplo de resposta:

```json
{
  "error": "onchain_invoice_not_found"
}
```

## Falha na entrega do webhook

Causa: Seu endpoint de webhook retornou uma resposta diferente de `2xx` ou expirou.

Solução: inspecione o corpo da resposta de entrega na página Webhooks, implemente uma correção e, em seguida, reproduza o evento.

Tentar novamente: reproduza manualmente depois que o endpoint estiver íntegro.

Exemplo de registro de entrega:

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

## Token de acesso inválido

Causa: O token do portador TextTree está ausente, malformado, expirou, revogado ou não possui o
escopo necessário.

Solução: atualize a sessão do navegador, emita um novo token de agente ou inclua o escopo ausente.

Tentar novamente: tente novamente com um token válido.

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