Errores

Respuesta directa

Errores comunes de la API y de entrega de TextTree con causas, soluciones y guía de reintentos.

Contenido de la página

## Remitente o proveedor no listo

Causa: TextTree no pudo reservar un número de remitente o el proveedor de mensajería rechazó la solicitud.

Solución: Confirma que el workspace tenga un remitente conectado o un remitente disponible del grupo instantáneo, y luego reintenta después de
que se restablezca la disponibilidad del proveedor.

Reintento: Reintenta solo después de que se resuelva el problema del remitente o del proveedor.

Ejemplo de respuesta:

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

Causa: El número de teléfono del destinatario tiene una supresión activa a nivel de workspace. Esto suele provenir
de un evento STOP/baja (opt-out) del proveedor o de una supresión manual del operador.

Solución: Respeta la supresión o elimínala desde la Configuración del Workspace solo si tu proceso de cumplimiento
permite que ese destinatario vuelva a recibir SMS.

Reintento: No reintentes hasta que se elimine la supresión.

Ejemplo de respuesta:

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

## Campaña suprimida

Causa: El número de teléfono del destinatario tiene una baja (opt-out) activa para una campaña específica.

Solución: Mantén omitida la entrega de la campaña o elimina la baja de la campaña desde la página de la Campaña si
se creó por error.

Reintento: No reintentes la entrega generada hasta que se elimine la supresión de la campaña.

## Límite de gasto excedido

Causa: Se excedería el límite de gasto del workspace.

Solución: Aumenta el límite o espera hasta el próximo período de facturación.

Reintento: Reintenta solo cuando haya gasto disponible.

Ejemplo de respuesta:

```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: La cuenta no tiene suficiente saldo prepagado de SMS acreditado para el envío solicitado.

Solución: Crea una factura de financiamiento en USDC, paga el monto exacto y espera a que el estado de la factura pase a
`paid` antes de reintentar.

Reintento: Reintenta después de que se acredite el saldo.

Ejemplo de respuesta:

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

## Monto por debajo del mínimo

Causa: El monto de la factura de financiamiento está por debajo del mínimo actual de onboarding o del producto.

Solución: Envía un monto mayor que cumpla con el `minimum_cents` devuelto.

Reintento: Reintenta de inmediato con un monto válido.

Ejemplo de respuesta:

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

## Factura onchain no encontrada

Causa: La factura no existe para el usuario autenticado o el ID es incorrecto.

Solución: Usa el ID de factura devuelto por `POST /api/v1/onboarding/funding-invoices` o
`onboarding.create_invoice`.

Reintento: Reintenta con un ID de factura válido.

Ejemplo de respuesta:

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

## Falla en la entrega del webhook

Causa: Tu endpoint de webhook devolvió una respuesta no `2xx` o se agotó el tiempo de espera.

Solución: Inspecciona el cuerpo de la respuesta de la entrega en la página de Webhooks, despliega una corrección y luego reproduce el evento.

Reintento: Reproduce manualmente después de que el endpoint esté saludable.

Ejemplo de registro de entrega:

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

## Token de acceso inválido

Causa: El token bearer de TextTree falta, está mal formado, expiró, fue revocado o carece del
scope requerido.

Solución: actualiza la sesión del navegador, emite un nuevo token de agente o incluye el scope faltante.

Reintento: Reintenta con un token válido.

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