Por qué un handle de Bluesky con dominio no es válido y cómo arreglarlo
Cómo verifica Bluesky un handle con dominio: el registro TXT _atproto, el archivo atproto-did, el documento DID, cada comprobación y los errores habituales.
Cómo verifica Bluesky un handle con dominio
Un handle es un nombre de dominio. Bluesky acepta alice.example.com como tu
handle cuando puede comprobar el vínculo en los dos sentidos:
- El dominio apunta a tu cuenta. O bien un registro DNS
TXTllamado_atproto.alice.example.comcuyo valor esdid=seguido de tu DID, o bien el archivohttps://alice.example.com/.well-known/atproto-didcuyo único contenido es tu DID. Basta con uno de los dos. - Tu cuenta apunta de vuelta al dominio. Tu documento DID indica el
handle en
alsoKnownAscomoat://alice.example.com. Bluesky lo escribe ahí cuando cambias tu handle en la app.
Las reglas están en la especificación de los handles del AT Protocol. Para las otras formas de conseguir un handle, lee la guía Cómo conseguir un handle personalizado en Bluesky.
El registro que debes añadir
| Handle | Host / Nombre | Tipo | Valor |
|---|---|---|---|
example.com | _atproto | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
alice.example.com (zona example.com) | _atproto.alice | TXT | did=did:plc:ewvi7nxzyoun6zhxrhs64oiz |
Los paneles DNS añaden tu zona al nombre por sí solos: escribe la parte de
_atproto.<handle> anterior a la zona, no el nombre completo. El verificador
encuentra la zona con una consulta SOA y muestra el host exacto. El valor
empieza por did=, sin comillas ni espacios: Bluesky lee un solo valor que
empiece por did=, tal cual, sin recortar nada.
El archivo es la otra forma, para un alojamiento sin panel DNS. Es texto plano, servido con el código 200:
did:plc:ewvi7nxzyoun6zhxrhs64oizQué comprueba la herramienta
La herramienta hace siete comprobaciones, en orden. Cada una es correcta,
falla, avisa o no se hace, con un código de motivo (las respuestas de la API y
de MCP dan ese código en checks[].reason).
| Comprobación | Falla cuando (motivo) |
|---|---|
syntax | el dominio no es un handle válido: más de 253 caracteres (too_long), una sola parte (single_label), una parte vacía o de más de 63 caracteres (label_length), un carácter distinto de a–z, 0–9 y - (characters), un guion al principio o al final de una parte (hyphen), un dominio de nivel superior que empieza por una cifra (tld_digit), un dominio de nivel superior reservado como .local o .example (disallowed_tld) |
dns | ningún registro (missing), un espacio antes de did=, que Bluesky lee como ningún registro (leading_space), un DID sin did= (no_prefix), un valor que no es did= y un DID válido (invalid_value), el registro en el nombre equivocado (wrong_host: la zona dos veces, el _atproto de la propia zona o el propio dominio), dos o más valores que empiezan por did=, incluso iguales (conflict) |
https | ningún archivo (missing: un 404 o un 410), una página web en lugar del DID (html), algo más que el DID (extra_content), un contenido de más de 1 KB (too_large), otro código (status); avisa cuando el servidor no responde (unreachable) |
agreement | el registro y el archivo indican DID distintos (disagree) |
document | el documento DID declara otro handle o ninguno (claims_other), o no existe (not_found) |
expected | el dominio apunta a otra cuenta que la que indicaste (mismatch) |
appview | Bluesky muestra handle.invalid (invalid), el handle anterior (old_handle), o aún no asocia el dominio a la cuenta (unresolved) |
Que falte un método no es un problema cuando el otro funciona: la fila es
entonces correcta con not_needed. Un problema en el método que Bluesky no
usa es un aviso, salvo dos valores DNS que empiezan por did=, que el
resolutor de Bluesky trata como un fallo. El DNS manda, como en la
especificación: un DID dado por el DNS y declarado de vuelta por el documento
DID verifica el handle, responda lo que responda el servidor web.
Errores habituales
- La zona añadida dos veces. Un panel DNS añade tu zona al nombre:
escribir el nombre completo
_atproto.alice.example.comcrea_atproto.alice.example.com.example.com. Escribe solo el host que muestra el verificador (_atproto.aliceen la zonaexample.com). - El registro en el nombre de la zona. Para
alice.example.com, un registro en_atproto.example.comdesigna el handleexample.com, no el tuyo. El verificador busca un registrodid=ahí, en la zona añadida dos veces y en el propio dominio. - El DID sin
did=. El valor debe serdid=did:plc:…, con el prefijo. - Un espacio antes de
did=. Bluesky lee el valor tal cual:did=…cuenta como ningún registro. - Un registro antiguo olvidado. Bluesky lee un solo valor que empiece
por
did=: dos, incluso con el mismo DID, hacen que el handle no sea válido. Deja solo el tuyo. - Una página web en lugar del archivo. Muchos alojamientos responden a cualquier dirección desconocida con su página de inicio, código 200. El archivo debe contener solo el DID.
- El handle aún sin cambiar. Los registros están bien, pero tu documento DID aún declara el handle anterior: configura de nuevo el handle en Ajustes → Cuenta → Handle en la app de Bluesky.
- La espera del DNS. Un cambio puede tardar hasta una hora en llegar a todos los resolutores. La herramienta nunca guarda una respuesta en caché: vuelve a ejecutarla.
Sin DNS para un bot
Un bot puede usar un handle name.bluesky.bot en su lugar: Bluesky.bot sirve
el archivo y cambia el handle por ti. Consulta
Consigue tu handle, o comprueba si un nombre está
libre con el verificador de disponibilidad de handles.
Úsala desde el código
El verificador es también una ruta de API gratuita y una herramienta MCP,
check_custom_handle:
curl "https://bluesky.bot/api/v1/tools/custom-handle-checker?domain=alice.example.com"Cada llamada cuenta 2 en los límites. Consulta API de herramientas y servidor MCP.