API
Codigos de Error
Referencia de manejo de errores para la API de TBit
# Codigos de Error > Referencia de manejo de errores para la API de TBit - Página: https://tbit.app/es/docs/api/errors - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ¿Buscas por qué un mensaje de WhatsApp no se entregó? Revisa [Errores de entrega en WhatsApp](https://tbit.app/es/docs/errores-de-entrega-whatsapp). ## Formato de Respuesta de Error Todos los errores siguen una estructura JSON consistente: ```json { "error": { "code": "NOT_FOUND", "message": "Activity not found" } } ``` ## Codigos de Error | Estado | Código | Descripción | | --- | --- | --- | | `400` | `VALIDATION_ERROR` | Cuerpo de solicitud o parámetros de consulta inválidos | | `401` | `UNAUTHORIZED` | Clave API faltante o inválida | | `402` | `INSUFFICIENT_ENERGY` | No alcanza la energía; no se envió ni se llamó | | `404` | `NOT_FOUND` | Recurso no encontrado o no pertenece a tu agente | | `405` | `METHOD_NOT_ALLOWED` | Método HTTP no soportado para este endpoint | | `409` | `CONFLICT` | El recurso ya existe (por ejemplo, contacto con este canal) | | `409` | `NO_PHONE_LINE` | El agente no tiene una línea telefónica activa | | `422` | `SEND_FAILED` | Envío de plantilla fallido (por ejemplo, sin ventana de mensajería) | | `422` | `DESTINATION_NOT_ALLOWED` | El destino todavía no está habilitado (los +1 piden 10DLC) | | `429` | `RATE_LIMITED` | Límite de tasa excedido (100 solicitudes/minuto) | | `500` | `INTERNAL_ERROR` | Error inesperado del servidor | | `502` | `PROVIDER_ERROR` | El operador rechazó el envío o la llamada; message trae su motivo | ## Encabezados de límite de tasa Cada respuesta incluye información del límite de tasa en los encabezados: | Encabezado | Descripción | | --- | --- | | `X-RateLimit-Remaining` | Solicitudes restantes en la ventana actual | | `X-RateLimit-Reset` | Marca de tiempo (ms) cuando se reinicia la ventana | ## Manejo de Errores Mejores practicas para manejar errores de API: - Siempre verifica el código de estado HTTP antes de analizar el cuerpo de respuesta - Implementa backoff exponencial para errores 429 (límite de tasa) - Registra codigos y mensajes de error para depuracion - No reintentes errores 400 o 401: corrige la solicitud primero¿Buscas por qué un mensaje de WhatsApp no se entregó? Revisa Errores de entrega en WhatsApp.
Todos los errores siguen una estructura JSON consistente:
{
"error": {
"code": "NOT_FOUND",
"message": "Activity not found"
}
}| Estado | Código | Descripción |
|---|---|---|
400 | VALIDATION_ERROR | Cuerpo de solicitud o parámetros de consulta inválidos |
401 | UNAUTHORIZED | Clave API faltante o inválida |
402 | INSUFFICIENT_ENERGY | No alcanza la energía; no se envió ni se llamó |
404 | NOT_FOUND | Recurso no encontrado o no pertenece a tu agente |
405 | METHOD_NOT_ALLOWED | Método HTTP no soportado para este endpoint |
409 | CONFLICT | El recurso ya existe (por ejemplo, contacto con este canal) |
409 | NO_PHONE_LINE | El agente no tiene una línea telefónica activa |
422 | SEND_FAILED | Envío de plantilla fallido (por ejemplo, sin ventana de mensajería) |
422 | DESTINATION_NOT_ALLOWED | El destino todavía no está habilitado (los +1 piden 10DLC) |
429 | RATE_LIMITED | Límite de tasa excedido (100 solicitudes/minuto) |
500 | INTERNAL_ERROR | Error inesperado del servidor |
502 | PROVIDER_ERROR | El operador rechazó el envío o la llamada; message trae su motivo |
Cada respuesta incluye información del límite de tasa en los encabezados:
| Encabezado | Descripción |
|---|---|
X-RateLimit-Remaining | Solicitudes restantes en la ventana actual |
X-RateLimit-Reset | Marca de tiempo (ms) cuando se reinicia la ventana |
Mejores practicas para manejar errores de API:
- Siempre verifica el código de estado HTTP antes de analizar el cuerpo de respuesta
- Implementa backoff exponencial para errores 429 (límite de tasa)
- Registra codigos y mensajes de error para depuracion
- No reintentes errores 400 o 401: corrige la solicitud primero