API y webhooks
Errores de la API
El formato de los errores de la API de XBASE, qué quiere decir cada estado HTTP y la lista de códigos estables que tu integración debe tratar.
Actualizado el
Toda respuesta de error de la API tiene el mismo formato. Trata el error por el estado HTTP y por el code: el texto de message explica el problema, pero puede cambiar.
Formato
{
"statusCode": 401,
"timestamp": "2026-11-04T16:03:56.074Z",
"path": "/api/external/v1/me",
"method": "GET",
"message": "Chave de API inválida ou revogada.",
"code": "INVALID_API_KEY"
}| Campo | Descripción |
|---|---|
statusCode | Estado HTTP |
message | Qué salió mal, en texto |
code | Código estable del error. Los errores de validación (400) no tienen code |
details | Datos extra de algunos errores, como details.metaCode (el código del error en Meta) y details.reason |
timestamp · path · method | Cuándo y en qué ruta |
Estado HTTP
| Estado | Quiere decir |
|---|---|
| 200 · 204 | Funcionó (204 no tiene cuerpo) |
| 400 | Solicitud inválida: falta un campo o no cumple la regla. El message lista los campos |
| 401 | Clave ausente, inválida o revocada |
| 403 | La clave no tiene el alcance de la ruta |
| 404 | El recurso no existe en este workspace |
| 422 | Meta lo rechazó, la acción no cumple una regla de WhatsApp (como la ventana de 24 horas) o el recurso no está listo para ella |
| 5xx | Error en XBASE. Inténtalo de nuevo después de unos segundos |
Códigos
code | Estado | Cuándo |
|---|---|---|
INVALID_API_KEY | 401 | Sin encabezado Authorization, o la clave tiene un formato incorrecto, no existe o fue revocada |
MISSING_SCOPE | 403 | La clave no tiene el alcance de la ruta |
NOT_INCOMING_MESSAGE | 400 | Solo un mensaje recibido del contacto se puede marcar como leído |
NUMBER_NOT_FOUND | 404 | El número de WhatsApp (numberId) no es de este workspace |
TEMPLATE_NOT_FOUND | 404 | La plantilla no existe para este número |
MESSAGE_NOT_FOUND | 404 | El mensaje (messageId) no es de una conversación de WhatsApp de este workspace |
FLOW_NOT_FOUND | 404 | El Flow no es de la cuenta de WhatsApp del número |
NOT_FOUND | 404 | La cuenta de Instagram (connectionId) no es de este workspace |
NUMBER_DISCONNECTED | 422 | El número de WhatsApp está desconectado |
WINDOW_CLOSED | 422 | Mensaje libre de WhatsApp fuera de la ventana de 24 horas. details.reason dice el motivo |
UNSUPPORTED_FOR_NUMBER | 422 | El número no acepta este tipo de envío |
SEND_REJECTED | 422 | XBASE rechazó el envío antes de Meta, por ejemplo, faltan variables de la plantilla. El message dice el motivo |
META_ERROR | 422 | Meta rechazó la acción en WhatsApp o en Instagram. En WhatsApp, details.metaCode trae el código de Meta |
Buenas prácticas
- Trata el error por el
codey por el estado, no por el texto demessage. - En
5xx, inténtalo de nuevo con esperas crecientes (por ejemplo, 2, 10 y 30 segundos). - No repitas un envío de WhatsApp que devolvió
200: el contacto ya lo recibió. La API no evita envíos duplicados. - En
WINDOW_CLOSED, no repitas el mismo mensaje: envía una plantilla y espera que el contacto responda. - En
401, verifica que la clave no se haya revocado en Integraciones → Claves de API.