Códigos de error de webhooks (mpbx-webhooks)
Los genera las rutas de webhooks salientes bajo /api/v1/webhooks (W7-API-02). Los mensajes nunca contienen
un secreto de firma, una firma ni la respuesta de un receptor; como máximo nombran ids, nombres de campos y reglas.
Guía: Webhooks salientes.
| Código | HTTP | Significado | Qué hacer |
|---|---|---|---|
MPBX-WEBHOOK-NOT-FOUND | 404 | No existe ese endpoint en esta empresa (el endpoint de otra empresa no es visible). | Verifique el id. |
MPBX-WEBHOOK-DELIVERY-NOT-FOUND | 404 | No existe esa entrega en esta empresa, o fue purgada (las entregas exitosas se conservan 7 días, las fallidas definitivas 30 días). | Verifique el id. |
MPBX-WEBHOOK-URL-INVALID | 400 | La URL está vacía, tiene más de 2048 caracteres, no es una URL, o tiene espacios, caracteres de control o un fragmento. | Envíe una https://host[:port]/path?query sencilla. |
MPBX-WEBHOOK-URL-BLOCKED | 400 | La URL no está permitida: no es https, incluye información de usuario, usa un puerto menor de 1024 distinto de 443, o es una dirección privada, de loopback, link-local (metadatos de la nube), NAT de nivel de operador, de documentación, multicast o reservada (incluidas las formas IPv4-mapped y NAT64), o un nombre interno (localhost, *.local, *.internal, una sola etiqueta). La misma verificación se repite en cada entrega después de resolver el nombre. | Use una dirección pública https. |
MPBX-WEBHOOK-EVENT-TYPE-UNKNOWN | 400 | Una entrada de event_types no es un tipo de evento ni un patrón topic.* al que pueda suscribirse (audit.* y webhook.test nunca lo son), o requiere un permiso de eventos que no posee para toda la empresa (messaging:read para sms.*, call_history:read para cdr.written, ...; vea "Quién recibe qué" en la guía de webhooks). También ocurre al cambiar la URL de un endpoint cuyo filtro nombra esos eventos. | Use GET /api/v1/webhooks/event-types, que lista solo lo que puede recibir, o pida a alguien que tenga el permiso. |
MPBX-WEBHOOK-NAME-TAKEN | 409 | Otro endpoint de la empresa tiene este nombre. | Elija otro nombre. |
MPBX-WEBHOOK-FIELD-INVALID | 400 | Un campo está fuera de rango: name (de 1 a 80 caracteres), rate_per_minute (de 1 a 6000), grace_period_seconds (de 0 a 604800), o más de 64 entradas de filtro. | Corrija el campo indicado. |
MPBX-WEBHOOK-CHANGED | 409 | El endpoint cambió entre su lectura y su escritura. | Vuelva a leerlo y reintente con el nuevo ETag. |
MPBX-WEBHOOK-LIMIT-REACHED | 409 | La empresa ya tiene 20 endpoints. | Elimine uno, o envíe más tipos de evento a un solo endpoint. |
MPBX-WEBHOOK-RATE-LIMITED | 429 | Más de 10 entregas de prueba y reenvíos en un minuto para la empresa. | Espere un minuto (Retry-After: 60). |
MPBX-WEBHOOK-SECRET-UNREADABLE | 500 | No se puede abrir el secreto de firma sellado del endpoint (se reemplazó la clave maestra sin volver a cifrarla, o el registro está dañado). Las entregas a este endpoint fallan. | Rote el secreto (POST /webhooks/{id}/rotate-secret) y entregue el nuevo al receptor. |
MPBX-WEBHOOK-NOT-REDELIVERABLE | 409 | La entrega todavía está pendiente (esperando un intento o un reintento); solo una entrega exitosa o fallida definitiva puede volver a enviarse. | Espere a que termine, o revise sus intentos. |
MPBX-WEBHOOK-LOG-UNAVAILABLE | 503 | El registro de intentos necesita ClickHouse, que esta instalación no tiene, o no se pudo leer una fila del registro. Las entregas siguen funcionando; solo falta el historial. | Configure clickhouse.url. |
MPBX-WEBHOOK-ENDPOINT-DISABLED | 409 | Se pidió una prueba para un endpoint que está desactivado. | Actívelo primero (PATCH con enabled: true). |
Códigos de error de entrega
Un intento fallido guarda un código corto legible por máquina como last_error de la entrega (y en el registro de
intentos). Nunca es texto del receptor.
last_error | Significado | Se reintenta |
|---|---|---|
http_status | El receptor respondió con un estado fuera de 2xx (vea last_status). Un 3xx es un fallo: nunca se siguen redirecciones. Retry-After (segundos, como máximo una hora) alarga la espera. | sí |
timeout | Sin respuesta en 10 segundos (conexión en 5). | sí |
network | La conexión o el protocolo TLS falló o se interrumpió. | sí |
dns | El nombre de host no se resolvió. | sí |
blocked | El destino resolvió a una dirección que no está permitida (vea MPBX-WEBHOOK-URL-BLOCKED). | no: fallida definitiva de inmediato |
too_large | El cuerpo es mayor de 256 KiB. | no: fallida definitiva de inmediato |
rate_limit | No es un fallo: se agotó el rate_per_minute del endpoint, la entrega espera unos segundos (se registra como deferred, sin contar un intento). | no aplica |