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:
- O domínio aponta para a sua conta. Ou um registo DNS
TXTchamado_atproto.alice.example.comcujo valor édid=seguido do seu DID, ou o ficheirohttps://alice.example.com/.well-known/atproto-didcujo único conteúdo é o seu DID. Basta um dos dois. - A sua conta aponta de volta para o domínio. O seu documento DID indica
o handle em
alsoKnownAscomoat://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
| Handle | Anfitrião / Nome | Tipo | Valor |
|---|---|---|---|
example.com | _atproto | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
alice.example.com (zona example.com) | _atproto.alice | TXT | did=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:
did:plc:ewvi7nxzyoun6zhxrhs64oizO 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ção | Falha quando (motivo) |
|---|---|
syntax | o 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) |
dns | nenhum 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) |
https | nenhum 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) |
agreement | o registo e o ficheiro indicam DID diferentes (disagree) |
document | o documento DID declara outro handle ou nenhum (claims_other), ou não existe (not_found) |
expected | o domínio aponta para outra conta que não a indicada (mismatch) |
appview | o 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.comcria_atproto.alice.example.com.example.com. Escreva apenas o anfitrião que o verificador mostra (_atproto.alicena zonaexample.com). - O registo no nome da zona. Para
alice.example.com, um registo em_atproto.example.comdesigna o handleexample.com, e não o seu. O verificador procura um registodid=aí, na zona acrescentada duas vezes e no próprio domínio. - O DID sem
did=. O valor tem de serdid=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:
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.