Límites de velocidad y errores API
Los puntos finales Telemetry utilizan códigos de estado estándar HTTP. Los clientes deben distinguir un defecto de solicitud de un servicio temporal o condición de capacidad antes de volver a intentarlo.
Las cuotas específicas del plan y los límites actuales pueden cambiar. Tratar los límites que se muestran en la configuración del producto y de facturación como la fuente de verdad para una cuenta; no codifique una tasa de solicitud global no documentada.
Clases de respuesta
| Estado | Significado | Acción del cliente |
|---|---|---|
200 o 202 |
La operación se realizó correctamente o se aceptó un trabajo asincrónico | Lea el cuerpo de la respuesta y continúe |
400 |
JSON, SQL, nombre de tabla, tipo de campo o forma de solicitud no válidos | Arreglar la solicitud; no volver a intentarlo sin cambios |
401 |
Clave API faltante, no válida o revocada | Reemplazar la credencial |
403 |
La clave no tiene el alcance requerido. | Utilice la clave de alcance correcta |
404 |
La tabla, trabajo, panel, alerta o ruta solicitada no existe | Verificar el identificador y el equipo |
409 o 422 |
La solicitud entra en conflicto con el estado actual o no se puede aplicar. | Inspeccionar el error y cambiar la operación. |
429 |
Se superó la tasa o cuota de solicitud actual | Respete el Retry-After cuando esté presente y retroceda. |
5xx |
Telemetry no pudo completar una solicitud válida | Reintentar un número limitado de veces con retroceso |
Los cuerpos de error pueden incluir un contexto más específico. Registre el estado, el nombre del punto final, el ID de la solicitud y una categoría de error seguro. No registre la clave API o la carga útil del evento original simplemente porque falló una solicitud.
Reintentar de forma segura
Utilice un retroceso exponencial con fluctuación para las respuestas 429, 502, 503 y 504. Limite tanto los intentos como el tiempo total transcurrido para que una interrupción de la telemetría no pueda agotar a un trabajador de la aplicación.
delay = min(max_delay, base_delay * 2^attempt) + random_jitter
No vuelva a intentar una respuesta 400 sin modificar la solicitud. El envío repetido de un esquema no válido o una consulta SQL genera carga sin crear una ruta hacia el éxito.
Preservar la identidad del evento
Al volver a intentar la ingesta, reutilice un event_id estable para el evento lógico. Esto hace que la entrega duplicada sea mensurable y permite que un consumidor idempotente reconozca los reintentos. Un nuevo identificador en cada intento de red convierte un resultado en varios eventos comerciales indistinguibles.
Utilice el receta de ID de evento duplicado para auditar el comportamiento de los reintentos.
Impacto de falla ligado
Decida si la telemetría se encuentra en la ruta crítica. Para la mayoría de los instrumentos de productos, una falla de ingesta temporal debe informarse a través de un canal de diagnóstico seguro sin cambiar una respuesta del cliente que ya tuvo éxito. Para flujos de trabajo de cumplimiento o facturación, una cola duradera puede ser adecuada.
Para conjuntos de resultados grandes, utilice Consulta asincrónica API en lugar de volver a intentar repetidamente una solicitud interactiva. Consulte Claves de API y autenticación para conocer las reglas de alcance.