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.
Errores de una prueba anónima
Con una clave anon_…, lea el code JSON además del estado HTTP. Un 403 no siempre indica una clave incorrecta, y esperar no resuelve todos los 429.
| Código | Estado | Qué hacer |
|---|---|---|
anonymous_signup_required |
403 |
El período de lectura anónima terminó 24 horas después del primer evento. Use el signup_url privado de la respuesta para vincular el espacio existente a una cuenta y conservar sus datos. No sustituya la clave ni cree otra prueba para recuperar esos eventos. |
anonymous_account_required |
403 |
Esta función requiere una cuenta. Vincule la prueba para seguir usando su espacio. |
anonymous_rate_limited |
429 |
Espere y vuelva a intentarlo con esperas crecientes y un límite de reintentos. |
anonymous_table_limit o anonymous_free_limit |
429 |
Se agotó el límite de tablas o de uso de la prueba. Vincule el espacio y revise los límites de la cuenta; esperar no restablece el cupo de la prueba. |
anonymous_invalid_batch |
413 |
Reduzca el tamaño del lote y compruebe el nombre de la tabla según el mensaje de respuesta antes de reintentar. |
anonymous_expired |
410 |
La prueba sin vincular ha caducado y ya no puede recuperarse vinculándola. Empiece de nuevo con una cuenta; deje de reintentar con esta clave. |
El enlace de vinculación es privado: no publique signup_url en tickets ni registros. En otro navegador, abra la página de vinculación y use la opción para introducir una clave API anónima existente. Vincular la prueba conserva su espacio y su clave.
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.