Verificar meu backlink retornou nada: uma tabela de erros

A regra que cobre a maioria dos casos

Retentar falhas de rede. Nunca retentar 401 ou 402. O primeiro se resolve em segundos; o segundo precisa de um humano, e insistir apenas enche seus logs.

Cada resposta JSON contém um campo ok, e as autenticadas adicionam _credits com o custo da chamada e o saldo restante. Verifique ok no corpo mesmo quando o status HTTP parecer correto.

Os tempos de nova tentativa abaixo são nossa recomendação de engenharia, não limites documentados. A documentação da API que possuímos não publica um limite de taxa, então crie seu próprio teto e mantenha-o moderado.

Por que 401 e 402 nunca são retentados

Um 401 é um problema de chave, e um 402 é um problema de saldo. Nenhum dos dois se resolve entre duas tentativas separadas por um segundo, então uma nova tentativa adiciona ruído aos seus logs e nada mais.

Esperar também não resolve um 402. O saldo permanece onde está até que alguém o recarregue na página da conta, então a única reação útil é uma mensagem clara e um alerta para quem possui o orçamento.

Um 401 merece uma olhada no cabeçalho ou no parâmetro key, e uma verificação de que a chave não foi substituída. Retentar a mesma chave errada algumas vezes não prova nada.

Uma chave inválida e um saldo vazio também parecem diferentes no seu painel. Coloque-os em alertas separados, para que a pessoa que recarrega não seja acordada por um erro de digitação na chave, e a pessoa que rotaciona chaves não seja notificada por um saldo.

Falhas de rede e backoff

Um tempo limite ou uma reinicialização de conexão podem ser resolvidos automaticamente, então esses são os únicos casos que valem a pena tentar novamente. Aguarde 1, 2, 4 e depois 8 segundos, adicione um pouco de jitter e pare após a quarta tentativa.

Esses tempos são nossa recomendação, não um limite documentado. Mantenha seu próprio teto, registre cada nova tentativa e alerte quando as novas tentativas aumentarem, porque uma taxa de novas tentativas crescente é geralmente o primeiro sinal de um problema na origem.

Mantenha o tempo limite do seu lado explícito, em uma constante nomeada. Um padrão implícito que muda com uma atualização de biblioteca é uma razão comum para um trabalho noturno começar a falhar apenas em uma máquina.

Observe o tempo de resposta da origem, bem como a taxa de falhas. Uma resposta lenta que nunca falha ainda pode ocupar seus workers, e um loop de nova tentativa piora esse atraso.

Normalize o domínio antes da chamada

A maioria das chamadas falhas começa na caixa de entrada, não na rede. Os usuários colam o que copiaram, e seu código precisa transformar isso em um domínio nu antes que a API o veja.

Remova o esquema e o caminho

Remova o esquema, qualquer caminho e a string de consulta. Um endereço de artigo colado se torna seu host, e apenas o host vai para a origem.

Coloque o host em minúsculas também. Mantenha a limpeza em uma única função, para que a mesma regra seja executada no formulário, no trabalho em lote e nos testes.

Teste a limpeza com cinco ou seis entradas reais coladas, incluindo uma com barra final e uma com string de consulta. Esses casos revelam bugs que um exemplo limpo nunca mostra.

Decida uma vez o que fazer com o www.

Escolha uma regra para www. e aplique-a em uma única função, para que o mesmo site nunca seja consultado com duas grafias.

Escreva a regra ao lado da função. O próximo desenvolvedor que encontrar um www solitário encontrará então a decisão, não uma segunda opinião.

Qualquer que seja a regra escolhida, mantenha-a em um arquivo e escreva um teste para ela. O teste é o registro da decisão, e é curto.

Rejeite o que não pode ser um domínio

Recuse entradas com espaços ou rótulos vazios e mostre uma mensagem curta no formulário. Uma string rejeitada não custa nada, enquanto uma ruim custa uma chamada falha e um usuário confuso.

Pontos finais são o caso estranho. Remova um no final do host e trate qualquer outro como inválido.

Mostre a rejeição ao lado do campo, não como um toast que desaparece. Um usuário que pode ver o que estava errado corrige em uma tentativa.

Resultados vazios e a idade do índice

Quando alguém digita verificar meu backlink no seu formulário e não recebe nada, uma resposta vazia nem sempre é um erro. Muitas vezes significa que o domínio é novo, muito pequeno ou simplesmente ainda não está no índice, e a tela deve dizer qual.

Um site recém-lançado

Um site lançado na semana passada pode não ter domínios de referência no índice. Mostre "ainda não indexado" junto com a data de indexação e ofereça a chamada overview gratuita como uma verificação cruzada.

Não armazene em cache essa resposta vazia por muito tempo. Algumas horas são suficientes, e a próxima reconstrução pode trazer o site.

Informe ao visitante quando o índice foi reconstruído pela última vez, em palavras claras. Uma data ao lado de uma resposta vazia explica a lacuna melhor do que uma mensagem mais longa.

Uma nota de uma linha na sua própria interface é suficiente aqui. Ninguém espera um índice em tempo real, e uma frase simples ao lado da data de indexação parece honesta.

Um número que discorda de outra ferramenta

Crawlers diferentes veem fatias diferentes da web. Leia a figura DR como uma posição dentro de uma ferramenta e direcione os leitores para a referência DR para a fórmula.

Uma nota curta sob a figura economiza mais tempo de suporte do que qualquer quantidade de desculpas depois do fato.

Se duas leituras diferirem, compare primeiro as contagens de domínios de referência. A fórmula DR é simples, então a maioria das discordâncias se resume à contagem.

Linhas que param em 50.000

Quando uma lista para no teto, a resposta está correta para o que a API permite. Rótule o corte e vincule as notas de paginação em vez de tentar uma página mais profunda.

Páginas mais profundas além desse ponto não são uma nova tentativa. Elas são uma consulta diferente, e tratá-las como uma é como um loop roda por horas.

Mantenha o corte visível também na exportação, para que uma planilha aberta um mês depois ainda mostre que a lista foi limitada.

Mostrar a contagem de linhas ao lado da tabela transforma um corte em um fato visível. Um leitor que vê 50.000 linhas sabe pedir uma pergunta mais específica.