Documentação da ferramenta

Porque é que um handle de domínio do Bluesky é inválido e como o corrigir

Como o Bluesky verifica um handle de domínio: o registo TXT _atproto, o ficheiro atproto-did e o documento DID, cada verificação da ferramenta e os erros mais comuns.

Como o Bluesky verifica um handle de domínio

Um handle é um nome de domínio. O Bluesky aceita alice.example.com como o seu handle quando consegue verificar a ligação nos dois sentidos:

  1. O domínio aponta para a sua conta. Ou um registo DNS TXT chamado _atproto.alice.example.com cujo valor é did= seguido do seu DID, ou o ficheiro https://alice.example.com/.well-known/atproto-did cujo único conteúdo é o seu DID. Basta um dos dois.
  2. A sua conta aponta de volta para o domínio. O seu documento DID indica o handle em alsoKnownAs como at://alice.example.com. O Bluesky escreve-o lá quando muda o handle na app.

As regras estão na especificação dos handles do AT Protocol. Para as outras formas de obter um handle, leia o guia Como obter um handle personalizado no Bluesky.

O registo a adicionar

HandleAnfitrião / NomeTipoValor
example.com_atprotoTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz
alice.example.com (zona example.com)_atproto.aliceTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz

Os painéis DNS acrescentam a sua zona ao nome sozinhos: escreva a parte de _atproto.<handle> antes da zona, e não o nome completo. O verificador encontra a zona com uma consulta SOA e mostra o anfitrião exato. O valor começa por did=, sem aspas nem espaços: o Bluesky lê um único valor que comece por did=, tal como está, sem retirar nada.

O ficheiro é a outra forma, para um alojamento sem painel DNS. É texto simples, servido com o código 200:

text
did:plc:ewvi7nxzyoun6zhxrhs64oiz

O que a ferramenta verifica

A ferramenta faz sete verificações, por ordem. Cada uma está correta, falha, avisa ou não é feita, com um código de motivo (as respostas da API e do MCP dão esse código em checks[].reason).

VerificaçãoFalha quando (motivo)
syntaxo domínio não é um handle válido: mais de 253 caracteres (too_long), uma só parte (single_label), uma parte vazia ou com mais de 63 caracteres (label_length), um carácter diferente de a–z, 0–9 e - (characters), um hífen no início ou no fim de uma parte (hyphen), um domínio de topo que começa por um algarismo (tld_digit), um domínio de topo reservado como .local ou .example (disallowed_tld)
dnsnenhum registo (missing), um espaço antes de did=, que o Bluesky lê como nenhum registo (leading_space), um DID sem did= (no_prefix), um valor que não é did= e um DID válido (invalid_value), o registo no nome errado (wrong_host: a zona duas vezes, o _atproto da própria zona ou o próprio domínio), dois ou mais valores que começam por did=, mesmo iguais (conflict)
httpsnenhum ficheiro (missing: um 404 ou um 410), uma página web em vez do DID (html), mais do que o DID (extra_content), um conteúdo com mais de 1 KB (too_large), outro código (status); avisa quando o servidor não responde (unreachable)
agreemento registo e o ficheiro indicam DID diferentes (disagree)
documento documento DID declara outro handle ou nenhum (claims_other), ou não existe (not_found)
expectedo domínio aponta para outra conta que não a indicada (mismatch)
appviewo Bluesky mostra handle.invalid (invalid), o handle anterior (old_handle), ou ainda não associa o domínio à conta (unresolved)

A falta de um método não é um problema quando o outro funciona: a linha fica então correta com not_needed. Um problema no método que o Bluesky não usa é um aviso, exceto dois valores DNS que começam por did=, que o resolvedor do Bluesky trata como uma falha. O DNS prevalece, como na especificação: um DID dado pelo DNS e declarado de volta pelo documento DID verifica o handle, seja qual for a resposta do servidor web.

Erros comuns

  • A zona acrescentada duas vezes. Um painel DNS acrescenta a sua zona ao nome: escrever o nome completo _atproto.alice.example.com cria _atproto.alice.example.com.example.com. Escreva apenas o anfitrião que o verificador mostra (_atproto.alice na zona example.com).
  • O registo no nome da zona. Para alice.example.com, um registo em _atproto.example.com designa o handle example.com, e não o seu. O verificador procura um registo did= aí, na zona acrescentada duas vezes e no próprio domínio.
  • O DID sem did=. O valor tem de ser did=did:plc:…, com o prefixo.
  • Um espaço antes de did=. O Bluesky lê o valor tal como está: did=… conta como nenhum registo.
  • Um registo antigo esquecido. O Bluesky lê um único valor que comece por did=: dois, mesmo com o mesmo DID, tornam o handle inválido. Deixe apenas o seu.
  • Uma página web em vez do ficheiro. Muitos alojamentos respondem a qualquer endereço desconhecido com a página inicial, código 200. O ficheiro deve conter apenas o DID.
  • O handle ainda não mudou. Os registos estão certos, mas o seu documento DID ainda declara o handle anterior: defina de novo o handle em Definições → Conta → Handle na app do Bluesky.
  • A espera pelo DNS. Uma alteração pode demorar até uma hora a chegar a todos os resolvedores. A ferramenta nunca guarda uma resposta em cache: execute-a de novo.

Sem DNS para um bot

Um bot pode usar antes um handle name.bluesky.bot: o Bluesky.bot serve o ficheiro e muda o handle por si. Consulte Obter o seu handle, ou verifique se um nome está livre com o verificador de disponibilidade de handles.

Usar a partir de código

O verificador é também uma rota de API gratuita e uma ferramenta MCP, check_custom_handle:

bash
curl "https://bluesky.bot/api/v1/tools/custom-handle-checker?domain=alice.example.com"

Cada chamada conta 2 nos limites. Consulte API das ferramentas e servidor MCP.

Verificador de handles de domínio próprio

Descubra porque é que o seu handle é inválido e como o corrigir.