Documentación de la herramienta

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:

  1. El dominio apunta a tu cuenta. O bien un registro DNS TXT llamado _atproto.alice.example.com cuyo valor es did= seguido de tu DID, o bien el archivo https://alice.example.com/.well-known/atproto-did cuyo único contenido es tu DID. Basta con uno de los dos.
  2. Tu cuenta apunta de vuelta al dominio. Tu documento DID indica el handle en alsoKnownAs como at://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

HandleHost / NombreTipoValor
example.com_atprotoTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz
alice.example.com (zona example.com)_atproto.aliceTXTdid=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:

text
did:plc:ewvi7nxzyoun6zhxrhs64oiz

Qué 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ónFalla cuando (motivo)
syntaxel 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)
dnsningú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)
httpsningú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)
agreementel registro y el archivo indican DID distintos (disagree)
documentel documento DID declara otro handle o ninguno (claims_other), o no existe (not_found)
expectedel dominio apunta a otra cuenta que la que indicaste (mismatch)
appviewBluesky 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.com crea _atproto.alice.example.com.example.com. Escribe solo el host que muestra el verificador (_atproto.alice en la zona example.com).
  • El registro en el nombre de la zona. Para alice.example.com, un registro en _atproto.example.com designa el handle example.com, no el tuyo. El verificador busca un registro did= ahí, en la zona añadida dos veces y en el propio dominio.
  • El DID sin did=. El valor debe ser did=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:

bash
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.

Verificador de handles con dominio propio

Descubre por qué tu handle no es válido y cómo arreglarlo.