Límites de tasa

Respuesta directa

Comprende los límites de tasa de la API, el rendimiento de envío, los reintentos y los controles del modo en vivo.

Contenido de la página

Los límites de tasa protegen la confiabilidad de los proveedores, los controles de gasto y la experiencia del cliente.

TextTree muestra los fallos por límite de tasa con:

- ID de solicitud
- endpoint
- guía de reintento
- mensaje o evento de webhook relacionado

El rendimiento en producción depende del registro del remitente, los límites del proveedor y el plan del espacio de trabajo.

## Limitación del bootstrap de cuentas

El bootstrap de cuentas headless es intencionalmente más estricto que el tráfico normal de la API:

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

Cada dirección IP puede crear una cuenta exitosamente cada cinco minutos. TextTree
almacena solo un hash de la dirección IP para este registro de limitación. Un intento
de creación exitosa repetido dentro de la ventana devuelve:

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

## Límite de tasa de envío de mensajes

`POST /api/v1/messages` está limitado por tasa por credencial de API (por token de acceso) para
que una sola clave no pueda inundar la cola de envío compartida. El límite es un token bucket:
se permiten ráfagas cortas y luego las solicitudes se limitan a una tasa sostenida.

| Nivel de plan | Capacidad de ráfaga | Recarga de tokens |
| --- | ---: | --- |
| Starter | 1 mensaje | 1 token cada 1,200 ms |
| Growth | 5 mensajes | 1 token cada 1,200 ms |
| Scale | 10 mensajes | 1 token cada 1,200 ms |
| Enterprise | 20 mensajes | 1 token cada 1,200 ms |

Todos los niveles mantienen la recarga sostenida predeterminada de admisión de la API igual o por debajo del
techo predeterminado del proveedor Dial de un token cada 1,200 ms. Los niveles de pago aumentan
la admisión de ráfagas cortas; la entrega real todavía se encola detrás del registro del remitente,
los límites de tasa de Dial, los controles de gasto y la configuración de remitentes del espacio de trabajo.

Cuando el bucket está vacío, el endpoint responde con `429 Too Many Requests`, un
encabezado `Retry-After` (en segundos) y:

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

Las lecturas (`GET /api/v1/messages/:id`) y las vistas previas no se ven afectadas por este límite.
Hay disponible un rendimiento sostenido más alto por plan de espacio de trabajo una vez que el registro del
remitente sea estable — contacta a soporte.

## Formato de la respuesta

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

Usa `retry_after_seconds` cuando esté presente. Si el campo falta, usa retroceso exponencial con
jitter en lugar de reintentar inmediatamente.

## Patrón de reintento

```js
async function sendWithBackoff(payload, attempt = 1) {
  const response = await fetch("https://api.texttree.ai/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TEXTREE_ACCESS_TOKEN}`,
      "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);
}
```

## Idempotencia

Incluye siempre `idempotency_key` al reintentar envíos de flujos de trabajo. Esto permite que TextTree devuelva el
mensaje original en lugar de crear registros de SMS duplicados cuando la primera solicitud tuvo éxito pero
tu cliente agotó el tiempo de espera.

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

## Guía operativa

- Haz pruebas de ráfagas en modo Test antes de mover tráfico a Live.
- Mantén los receptores de webhooks rápidos y devuelve `2xx` con rapidez.
- Usa los registros de mensajes y los IDs de solicitud para depurar envíos limitados.
- Solicita a soporte un mayor rendimiento en producción una vez que el registro del remitente sea estable.