Comprueba mi backlink devolvió nada: una tabla de errores

La regla que cubre la mayoría de los casos

Reintenta los fallos de red. Nunca reintentes 401 ni 402. El primero se soluciona en segundos; el segundo requiere intervención humana, y presionar solo llena tus registros.

Cada respuesta JSON incluye un campo ok, y las autenticadas añaden _credits con el coste de la llamada y el saldo restante. Comprueba ok en el cuerpo incluso cuando el estado HTTP parezca correcto.

Los tiempos de reintento que se indican a continuación son nuestro consejo de ingeniería, no límites documentados. La documentación de la API que poseemos no publica un límite de velocidad, así que establece tu propio techo y manténlo moderado.

Por qué 401 y 402 nunca se reintentan

Un 401 es un problema de clave, y un 402 es un problema de saldo. Ninguno se resuelve entre dos intentos separados por un segundo, por lo que un reintento solo añade ruido a tus registros.

Esperar tampoco soluciona un 402. El saldo permanece donde está hasta que alguien lo recargue desde la página de la cuenta, por lo que la única reacción útil es un mensaje claro y una alerta a quien gestione el presupuesto.

Un 401 merece una revisión del encabezado o del parámetro key, y una comprobación de que la clave no haya sido reemplazada. Reintentar la misma clave incorrecta varias veces no demuestra nada.

Una clave incorrecta y un saldo vacío también se ven diferentes en tu panel. Ponlos en alertas separadas, para que quien recargue no se despierte por un error tipográfico en la clave, y quien rote las claves no sea notificado por un problema de saldo.

Fallos de red y retroceso

Un tiempo de espera o una reconexión pueden resolverse por sí solos, por lo que esos son los únicos casos que merecen otro intento. Espera 1, 2, 4 y luego 8 segundos, añade un poco de aleatoriedad y detente después del cuarto intento.

Esos tiempos son nuestro consejo, no un límite documentado. Mantén tu propio techo, registra cada reintento y alerta cuando los reintentos aumenten, porque una tasa de reintentos creciente suele ser la primera señal de un problema en el servicio upstream.

Mantén el tiempo de espera de tu lado explícito, en una constante con nombre. Un valor por defecto implícito que cambia con una actualización de la biblioteca es una razón común por la que un trabajo nocturno empieza a fallar solo en una máquina.

Observa también el tiempo de respuesta del servicio upstream junto con la tasa de fallos. Una respuesta lenta que nunca falla aún puede ocupar tus trabajadores, y un bucle de reintentos empeora esa lentitud.

Normaliza el dominio antes de la llamada

La mayoría de las llamadas fallidas comienzan en la caja de entrada, no en la red. Los usuarios pegan lo que copiaron, y tu código debe convertir eso en un dominio limpio antes de que la API lo vea.

Elimina el esquema y la ruta

Elimina el esquema, cualquier ruta y la cadena de consulta. Una dirección de artículo pegada se convierte en su host, y solo el host va al servicio upstream.

Convierte el host a minúsculas también. Mantén la limpieza en una sola función, para que la misma regla se ejecute en el formulario, en el trabajo por lotes y en las pruebas.

Prueba la limpieza con cinco o seis entradas reales pegadas, incluyendo una con una barra final y otra con una cadena de consulta. Esos casos revelan errores que un ejemplo limpio nunca muestra.

Decide una vez qué hacer con www.

Elige una regla para www. y aplícala en una sola función, para que el mismo sitio nunca se busque con dos grafías.

Escribe la regla junto a la función. El siguiente desarrollador que encuentre un www perdido encontrará entonces la decisión, no una segunda opinión.

Cualquiera que sea la regla que elijas, mantenla en un solo archivo y escribe una prueba para ella. La prueba es el registro de la decisión, y es breve.

Rechaza lo que no puede ser un dominio

Rechaza entradas con espacios o etiquetas vacías, y muestra un mensaje corto en el formulario. Una cadena rechazada no cuesta nada, mientras que una incorrecta cuesta una llamada fallida y un usuario confundido.

Los puntos finales son el caso extraño. Elimina uno al final del host y trata cualquier otro como inválido.

Muestra el rechazo junto al campo, no como una notificación que desaparece. Un usuario que puede ver qué estaba mal lo corrige en un solo intento.

Resultados vacíos y la antigüedad del índice

Cuando alguien escribe comprueba mi backlink en tu formulario y no obtiene nada, una respuesta vacía no siempre es un error. A menudo significa que el dominio es nuevo, demasiado pequeño o simplemente no está en el índice aún, y la pantalla debería decir cuál.

Un sitio recién lanzado

Un sitio lanzado la semana pasada puede no tener dominios de referencia en el índice. Muestra "no indexado aún" junto con la fecha del índice, y ofrece la llamada gratuita overview como una comprobación cruzada.

No almacenes en caché esa respuesta vacía por mucho tiempo. Unas pocas horas son suficientes, y la próxima reconstrucción puede incluir el sitio.

Dile al visitante cuándo se reconstruyó el índice por última vez, en palabras claras. Una fecha junto a una respuesta vacía explica la brecha mejor que un mensaje más largo.

Una nota de una línea en tu propia interfaz es suficiente aquí. Nadie espera un índice en tiempo real, y una frase sencilla junto a la fecha del índice se lee como honesta.

Un número que no coincide con otra herramienta

Los rastreadores diferentes ven diferentes partes de la web. Lee la figura DR como una posición dentro de una herramienta, y señala a los lectores a la referencia DR para la fórmula.

Una nota corta debajo de la figura ahorra más tiempo de soporte que cualquier cantidad de disculpas posteriores.

Si dos lecturas difieren, compara primero los conteos de dominios de referencia. La fórmula DR es simple, por lo que la mayoría de las discrepancias se reducen al conteo.

Filas que se detienen en 50.000

Cuando una lista se detiene en el techo, la respuesta es correcta para lo que permite la API. Etiqueta el corte y enlaza las notas de paginación en lugar de intentar una página más profunda.

Las páginas más profundas más allá de ese punto no son un reintento. Son una consulta diferente, y tratarlas como una es cómo un bucle se ejecuta durante horas.

Mantén el corte visible en la exportación también, para que una hoja de cálculo abierta un mes después aún muestre que la lista estaba limitada.

Mostrar el conteo de filas junto a la tabla convierte un corte en un hecho visible. Un lector que vea 50.000 filas sabrá pedir una pregunta más específica.