Códigos de error de Universal Links y App Links, explicados
SWCERR00101, SWCERR00301, legacy_failure, 1026: qué significa de verdad cada error de Universal Links y de Android App Links, dónde aparece y qué arreglo hace que la app vuelva a abrirse. O deja que el validador gratuito de Appy encuentre el problema por ti en segundos.
Primero, asegúrate de que de verdad está roto
Muchas quejas de «los Universal Links no funcionan» son enlaces que se comportan exactamente como Apple los diseñó. La nota técnica TN3155 de Apple enumera los casos en los que la app tiene que quedarse cerrada: una URL escrita o pegada en la barra de direcciones de Safari es navegación directa, así que el navegador se la queda. Un enlace al mismo dominio de la página en la que estás también se queda en el navegador. Y los navegadores de terceros, incluidos los que van dentro de otras apps, deciden por su cuenta si le pasan un enlace a tu app.
Así que haz una prueba honesta antes de tocar un solo archivo. Pega el enlace en Notas en el iPhone y mantenlo pulsado. Si la configuración es correcta, el menú ofrece abrirlo en tu app además de en el navegador. Lo que el usuario elija ahí pasa a ser la opción por defecto para ese dominio: otro motivo silencioso por el que un enlace que ayer funcionaba hoy abre Safari.
Si Notas no ofrece la opción de la app, algo falla en la asociación, y el código de error te dice qué.
El atajo: el validador gratuito de Appy
Antes de abrir una terminal, pega tu dominio en el validador de Universal Links de Appy. Descarga tu archivo apple-app-site-association de tu propio servidor y, por separado, del CDN de Apple, así que ves al instante si Apple tiene el mismo archivo que tú. También le pregunta a la Digital Asset Links API de Google qué lee Android en tu assetlinks.json. Gratis, sin registro y con una sola página de resultados que puedes pasar a tus desarrolladores.
Si el problema son los propios archivos, el generador de AASA y assetlinks.json de Appy escribe los dos a partir de tu Team ID, tu bundle ID y tu huella SHA-256. El resto de esta guía explica cada error, para que sepas exactamente qué arreglar cuando el validador te marque uno.
Pregúntale al CDN de Apple qué tiene
Desde iOS 14, los teléfonos nunca descargan tu archivo apple-app-site-association de tu servidor. Lo obtienen del CDN de Apple, que a su vez lo descarga de ti. Así que la primera pregunta no es «¿está bien mi archivo?», sino «¿qué tiene Apple?».
Lo que el CDN de Apple guarda para tu dominio
curl -sD - "https://app-site-association.cdn-apple.com/a/v1/links.example.com" -o /dev/nullAsí responde un dominio que falla
HTTP/1.1 404 Not Found
Apple-Failure-Reason: SWCERR00101 Bad HTTP Response: 404 Not Found
Cache-Control: max-age=3600,publicTu propio servidor, tal como lo ve el CDN
curl -v -A "AASA-Bot/1.0" https://links.example.com/.well-known/apple-app-site-associationLos códigos SWCERR y cómo se arreglan
Apple no publica una lista de estos códigos. Los de abajo son los mensajes que el CDN de Apple devuelve en la cabecera Apple-Failure-Reason, cada uno confirmado en hilos de los Apple Developer Forums o en nuestras propias peticiones al CDN.
SWCERR00101 · Bad HTTP Response: 404 Not Found
El CDN pidió tu archivo y recibió algo distinto de un 200. Lo más habitual es que el archivo esté en el dominio raíz mientras el entitlement nombra un subdominio, o al revés. Cada host de applinks: necesita su propio archivo en https://<host>/.well-known/apple-app-site-association. Un 502 aquí significa que tu origen estaba caído cuando Apple preguntó.
SWCERR00201 · Insecure (non-https) redirects forbidden
La URL del archivo redirige a una dirección http://. Sírvelo directamente por HTTPS en todos los dominios. La documentación de Apple dice que nada de redirecciones; en nuestras pruebas, el CDN siguió una redirección de https a https, pero una que baja a http falla siempre.
SWCERR00202 · Connections to private/reserved IP addresses are not allowed
El nombre de host resuelve a una dirección privada o reservada, así que Apple no se conecta. Es típico en dominios de staging que solo existen dentro de una VPN. Para esos usa el modo desarrollador (más abajo) y, para producción, un host público.
SWCERR00301 · Timeout
El servicio de Apple que descarga el archivo esperó y no recibió ninguna cabecera. La causa habitual son firewalls, bloqueos geográficos y protecciones antibots que ponen a prueba a los clientes desconocidos. Apple dice que el archivo tiene que ser accesible desde cualquier IP y no publica sus rangos, así que abre esa ruta a todo el mundo.
SWCERR00302 · Network error (temporary)
Un fallo temporal, a menudo de DNS. Si tu DNS está bien, suele resolverse en la siguiente descarga, que tras un fallo llega antes de una hora.
SWCERR00303 · TLS error
El certificado ha caducado, se emitió para otro host, es autofirmado o falló el handshake. Apple necesita un certificado de confianza pública que cubra el nombre de host exacto. Un certificado para example.com no cubre links.example.com a menos que lo incluya expresamente.
SWCERR00305 · Network error
El CDN se conectó, pero la transferencia se cortó: EOF, connection refused o gzip: invalid header cuando el servidor anuncia una compresión que luego no envía. Revisa la configuración del WAF y de compresión para esa ruta concreta.
SWCERR00401 · Bad JSON content
El CDN recibió algo que no es JSON, normalmente una página HTML de verificación o una de inicio de sesión. El detalle «invalid character ‘<’» lo delata. La solución que dio un ingeniero de Apple en los foros: que el servidor devuelva el archivo tal cual a cualquier user agent, AASA-Bot/* incluido.
Comprueba las rutas con swcutil
Una vez que Apple tiene el archivo, la siguiente pregunta es si tu enlace coincide con él. En un Mac, swcutil prueba una copia local del archivo contra una URL real, que es la comprobación que los ingenieros de Apple recomiendan antes que el modo desarrollador.
Prueba de descarga
sudo swcutil dl -d links.example.comPrueba de coincidencia
sudo swcutil verify -d links.example.com -j ./apple-app-site-association -u https://links.example.com/promoAsí se ve una coincidencia
{ s = applinks, a = ABCD123.com.example.app, d = links.example.com }:
Pattern "https://links.example.com/promo" matched.Lo que piensa el propio teléfono
Con el modo de desarrollador activado, Ajustes › Desarrollador › Universal Links tiene una pantalla Diagnostics: escribes una URL completa y te dice si alguna app instalada la reclama. Para ver la historia completa, haz un sysdiagnose y abre swcutil_show.txt. Busca el ID de tu app y lee tres líneas.
Site/Fmwk Approval debería decir approved. Unspecified o denied significa que el teléfono nunca recibió un archivo aprobado para esa app y ese dominio: revisa el entitlement, el acceso público y el prefijo del Team ID. User Approval muestra si la persona eligió el navegador para este dominio. Last Checked y Next Check muestran cuándo descargó Apple tu archivo por última vez.
Ese último punto explica la mayoría de los momentos de «lo arreglé y no ha cambiado nada». Tras la instalación, el teléfono revisa el archivo más o menos una vez por semana. Para probar un arreglo ya, reinstala la app. Para staging, añade ?mode=developer a la entrada de applinks: se salta el CDN, pero solo en builds firmadas para desarrollo y en dispositivos donde lo hayas activado.
Las cifras que conviene recordar
- lo que el CDN de Apple conservó un archivo correcto en nuestras pruebas
- 6 h
- lo que conservó un fallo
- 1 h
- cada cuánto vuelve a comprobarlo un iPhone tras la instalación
- ~1 semana
- la espera mínima en Android antes de mirar la verificación
- 20 s
lo que el CDN de Apple conservó un archivo correcto en nuestras pruebas
lo que conservó un fallo
cada cuánto vuelve a comprobarlo un iPhone tras la instalación
la espera mínima en Android antes de mirar la verificación
Android App Links: los estados que muestra pm get-app-links
En Android no hay un CDN de por medio. El verificador del dispositivo descarga él mismo https://<host>/.well-known/assetlinks.json y, desde Android 12, un enlace sin verificar ya no muestra un selector: simplemente se abre en el navegador. Por eso una huella que falta se parece tanto a «el enlace funciona, pero no en mi app».
Android 12 también cambió cómo se evalúan varios hosts. Ahora cada host se verifica por separado; en Android 11 y versiones anteriores, un solo host que no pasa la verificación hace fallar a todos. Y en Android 15, un cambio en assetlinks.json puede tardar hasta siete días en llegar a todos los dispositivos.
Vuelve a lanzar la verificación desde tu portátil
Restablecer, verificar, leer
adb shell pm set-app-links --package com.example.app 0 all
adb shell pm verify-app-links --re-verify com.example.app
adb shell pm get-app-links com.example.appSalida típica
example.com: verified
sub.example.com: legacy_failure
example.org: 1026Qué significa cada estado
verified
El dominio pasó la verificación. Si los enlaces siguen abriendo el navegador, revisa el intent filter: android:autoVerify="true", la categoría BROWSABLE y los dos esquemas, http y https.
none
Todavía no hay nada registrado. Espera unos minutos y vuelve a ejecutar verify-app-links.
legacy_failure
El verificador antiguo rechazó el dominio sin decir por qué. Empieza por el propio archivo: HTTP 200, application/json, HTTPS, sin redirecciones.
1024 y superiores (por ejemplo, 1026)
Un error propio del verificador. La documentación de Android apunta a la red y al alojamiento: las mismas reglas de 200, JSON, HTTPS y sin redirecciones.
approved / denied
Forzado con un comando de shell, no por la verificación. Restablécelo con set-app-links antes de fiarte de ningún resultado.
migrated / restored / system_configured
Heredado de la verificación antigua, restaurado con los datos del usuario o fijado por la configuración del dispositivo. No son errores, pero tampoco demuestran que tu archivo funcione hoy.
La huella que está bien en tu portátil y mal en la Play Store
El fallo más común en Android no tiene nada que ver con el alojamiento. Con Play App Signing, Google vuelve a firmar tu app con su propia clave de firma de apps. El SHA-256 que sacas con keytool de tu clave de subida no es el que hay en los teléfonos de los usuarios, así que la build de release falla mientras tu build local pasa.
Copia en su lugar la huella que aparece en Play Console › Release › Setup › App signing. El array sha256_cert_fingerprints admite varios valores, así que deja ahí también tu clave de debug, en mayúsculas. Y recuerda que una redirección de example.com a www.example.com, o de http a https, hace que Android no verifique ninguno de tus enlaces.
Mira lo que Google lee de tu archivo
Digital Asset Links API
curl "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://example.com&relation=delegate_permission/common.handle_all_urls"Mantén tus campañas en marcha mientras lo arreglas
Unos archivos de asociación rotos no deberían costarte instalaciones. Un enlace de Appy lleva cada teléfono a su tienda en todos los planes, Huawei AppGallery incluida, y en Pro intenta abrir primero tu app, así que quien ya la tiene entra directamente en ella. Sin archivo AASA, sin SDK, sin publicar una versión nueva. Cuando tus Universal Links vuelvan a funcionar, sigue con el mismo enlace de Appy: los códigos impresos y las publicaciones no cambian.
appy.to/yourapp
funciona mientras depuras
- iPhoneTu app en Pro, o el App Store
- AndroidTu app en Pro, o Google Play
- HuaweiAppGallery
- OrdenadorTu web
Sigue leyendo
- Validador de Universal LinksComprueba de una vez tu AASA en tu servidor y en el CDN de Apple, además de assetlinks.json.
- Generador de AASA y assetlinks.jsonEscribe los dos archivos a partir de tu Team ID, tu bundle ID y tu SHA-256.
- Universal Links que abren Safari en lugar de la appLas causas de comportamiento, desde la regla del mismo dominio hasta la elección del usuario.
- Falla la verificación de Android App LinksUn repaso más a fondo del lado de Android.
Preguntas sobre códigos de error
¿Dónde veo los códigos SWCERR?
En la cabecera Apple-Failure-Reason cuando pides https://app-site-association.cdn-apple.com/a/v1/tu-dominio, en la salida de swcutil dl en un Mac y en el log de swcd en un dispositivo.
¿Hay alguna herramienta que compruebe todo esto de una vez?
Sí. El validador de Universal Links de Appy es gratuito y no pide registro. Comprueba tu archivo AASA en tu servidor y en el CDN de Apple, y tu assetlinks.json a través de la Digital Asset Links API de Google, y después te dice qué arreglar.
¿Cómo consigo que Apple recoja mi archivo AASA corregido?
No puedes purgar el CDN de Apple. Vuelve a descargarlo cuando caduca su caché, que en nuestras pruebas fue una hora para los fallos. Después, reinstala la app en tu teléfono de pruebas para que descargue la copia nueva en lugar de esperar a la comprobación semanal.
¿El archivo apple-app-site-association tiene un límite de tamaño?
Apple documentó un límite de 128 KB en 2016. La documentación actual no lo repite, pero si mantienes el archivo pequeño, la pregunta deja de importar.
¿Por qué mi enlace abre el navegador cuando lo escribo en Safari?
Es lo esperado. Las URL escritas y los enlaces dentro del mismo dominio se quedan en el navegador por diseño. Haz la prueba desde Notas o Mensajes.
¿Qué significa legacy_failure en Android?
El verificador antiguo rechazó el dominio y Android no dice por qué. Comprueba que assetlinks.json devuelve un 200 como application/json por HTTPS y sin redirecciones, y que incluye la huella de Play App Signing.
¿Puedo evitarme todo esto?
En parte. En el plan Pro, un enlace de Appy prueba primero el esquema de URL de tu app y, si no, lleva a la tienda correcta, así que funciona sin archivos AASA en tu propio dominio. Los Universal Links de verdad siguen necesitando la configuración de arriba.
Seguir explorando
App Links de Android sin verificar: diagnóstico en cinco minutos con adb
Desde Android 12, un App Link que falla la verificación de dominio se abre en el navegador en lugar de tu app — en silencio y no en todos los dispositivos. La lista adb que encuentra la causa rápido.
¿Universal Links abren Safari? Corrige AASA, App Links, redirecciones y headers
Flujo práctico para corregir universal links y app links que abren navegador en lugar de la app.
Cómo tratan los navegadores in-app los deep links: Instagram, TikTok, Facebook, Gmail, Telegram y más
Por qué tu enlace abre la app desde Safari pero muere dentro de Instagram: el tipo de navegador que usa cada app, las reglas de iOS y Android y lo documentado app por app, de Instagram a Telegram.
¿Buscas otra cosa? Explora todos los temas en el blog.
Deja de perder toques por enlaces rotos
Encuentra el archivo roto con el validador gratuito y, mientras tanto, mantén todas tus campañas funcionando con un enlace de Appy: la tienda correcta en todos los planes, tu app en Pro.