Limites de taxa

Resposta direta

Compreende os limites de taxa de API, desempenho de envio, novas tentativas e controles de modo ao vivo.

Conteúdo fonte

Os limites de tarifas protegem a confiabilidade do fornecedor, os controles de gastos e a experiência do cliente.

TextTree exibe falhas de limite de taxa com:

- ID da solicitação
-ponto final
- guia de nova tentativa
- mensagem ou evento de webhook relacionado

O desempenho na produção depende do registro do remetente, dos limites do provedor e do plano do espaço de trabalho.

## Limitação de inicialização da conta

A inicialização da conta headless é intencionalmente mais rigorosa que o tráfego normal da API:

-`POST /api/v1/accounts`
-`POST /mcp/accounts`

Cada endereço IP pode criar uma conta com sucesso a cada cinco minutos. TextTree
armazena apenas um hash do endereço IP para esse registro de limitação. uma tentativa
A criação bem-sucedida repetida na janela retorna:

```json
{
  "error": "account_creation_rate_limited",
  "retry_after_seconds": 300
}
```

## Limite de taxa de envio de mensagens

`POST /api/v1/messages` tem taxa limitada por credencial de API (por token de acesso) para
que uma única chave não pode inundar a fila de envio compartilhada. O limite é um token bucket:
rajadas curtas são permitidas e então as solicitações são limitadas a uma taxa sustentada.

| Nível do plano | Capacidade de explosão | Recarga de token |
| --- | ---: | --- |
| Iniciante | 1 mensagem | 1 token a cada 1.200 ms |
| Crescimento | 5 mensagens | 1 token a cada 1.200 ms |
| Escala | 10 mensagens | 1 token a cada 1.200 ms |
| Empresa | 20 mensagens | 1 token a cada 1.200 ms |

Todos os níveis mantêm a recarga sustentada padrão de admissão da API igual ou inferior ao
O limite padrão do provedor de discagem é de um token a cada 1.200 ms. Os níveis salariais aumentam
a admissão de rajadas curtas; a entrega real ainda está na fila atrás do registro do remetente,
Limites de taxa de discagem, controles de gastos e configurações de remetente do espaço de trabalho.

Quando o bucket está vazio, o endpoint responde com `429 Too Many Requests`, um
Cabeçalho `Retry-After` (em segundos) e:

```json
{
  "error": "message_send_rate_limited",
  "message": "Too many message send requests. Retry after the indicated delay.",
  "retry_after_seconds": 1,
  "limit": {
    "tier": "starter",
    "capacity": 1,
    "refill_ms": 1200
  }
}
```

Leituras (`GET /api/v1/messages/:id`) e visualizações não são afetadas por este limite.
Um desempenho sustentado mais alto está disponível por plano de espaço de trabalho, uma vez registrado o
o remetente está estável – entre em contato com o suporte.

## Formato de resposta

```json
{
  "error": "message_send_rate_limited",
  "message": "Too many message send requests. Retry after the indicated delay.",
  "retry_after_seconds": 30,
  "limit": {
    "tier": "growth",
    "capacity": 5,
    "refill_ms": 1200
  }
}
```

Use `retry_after_seconds` quando presente. Se o campo estiver faltando, use backspace exponencial com
jitter em vez de tentar novamente imediatamente.

## Padrão de nova tentativa

```js
async function sendWithBackoff(payload, attempt = 1) {
  const response = await fetch("https://api.texttree.ai/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer undefined`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });

  if (response.status !== 429) {
    return response;
  }

  const retryAfter = Number(response.headers.get("retry-after") || 2 ** attempt);
  await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  return sendWithBackoff(payload, attempt + 1);
}
```

## Idempotência

Sempre inclua `idempotency_key` ao tentar novamente envios de fluxo de trabalho. Isso permite que o TextTree retorne o
mensagem original em vez de criar registros SMS duplicados quando a primeira solicitação foi bem-sucedida, mas
Seu cliente expirou.

```json
{
  "phone_number": "+15551234567",
  "body": "Your appointment is tomorrow at 9 AM.",
  "idempotency_key": "appointment-123-reminder"
}
```

## Guia operacional

- Faça testes de explosão no modo Teste antes de mover o tráfego para Live.
- Mantenha os receptores de webhook rápidos e retorne `2xx` rapidamente.
- Use logs de mensagens e IDs de solicitação para depurar envios limitados.
- Solicite suporte para maior desempenho de produção quando o registro do remetente estiver estável.