Les codes d’erreur des Universal Links et App Links, expliqués
SWCERR00101, SWCERR00301, legacy_failure, 1026 : ce que signifie vraiment chaque erreur de Universal Links et d’Android App Links, où vous la voyez, et la correction qui permet à l’app de s’ouvrir à nouveau. Ou laissez le validateur gratuit d’Appy trouver le problème pour vous, en quelques secondes.
D’abord, vérifiez que c’est vraiment cassé
Beaucoup de signalements « les Universal Links ne marchent pas » concernent des liens qui se comportent exactement comme Apple l’a prévu. La note technique TN3155 d’Apple liste les cas où l’app doit rester fermée : une URL tapée ou collée dans la barre d’adresse de Safari est une navigation directe, donc le navigateur la garde. Un lien vers le même domaine que la page sur laquelle vous êtes reste lui aussi dans le navigateur. Et les navigateurs tiers, y compris ceux intégrés à d’autres apps, décident eux-mêmes s’ils confient un lien à votre app.
Faites donc un test honnête avant de modifier le moindre fichier. Collez le lien dans Notes sur l’iPhone et appuyez longuement dessus. Si la configuration est bonne, le menu propose de l’ouvrir dans votre app en plus du navigateur. Ce que l’utilisateur choisit à cet endroit devient le comportement par défaut pour ce domaine : encore une raison discrète pour laquelle un lien qui marchait hier ouvre Safari aujourd’hui.
Si Notes ne propose pas d’ouvrir l’app, quelque chose cloche dans l’association, et le code d’erreur vous dit quoi.
Le raccourci : le validateur gratuit d’Appy
Avant d’ouvrir un terminal, collez votre domaine dans le validateur de Universal Links d’Appy. Il récupère votre fichier apple-app-site-association sur votre propre serveur et, séparément, sur le CDN d’Apple : vous voyez tout de suite si Apple a le même fichier que vous. Il demande aussi à l’API Digital Asset Links de Google ce qu’Android lit dans votre assetlinks.json. Gratuit, sans inscription, avec une seule page de résultats à transmettre à vos développeurs.
Si ce sont les fichiers eux-mêmes qui posent problème, le générateur AASA et assetlinks.json d’Appy les rédige tous les deux à partir de votre Team ID, de votre bundle ID et de votre empreinte SHA-256. La suite de ce guide explique chaque erreur, pour que vous sachiez exactement quoi corriger quand le validateur en signale une.
Demandez au CDN d’Apple ce qu’il a
Depuis iOS 14, les téléphones ne récupèrent jamais votre fichier apple-app-site-association sur votre serveur. Ils l’obtiennent auprès du CDN d’Apple, qui le récupère chez vous. La première question n’est donc pas « mon fichier est-il correct ? » mais « qu’est-ce qu’Apple a en main ? ».
Ce que le CDN d’Apple détient pour votre domaine
curl -sD - "https://app-site-association.cdn-apple.com/a/v1/links.example.com" -o /dev/nullUn domaine en échec répond ainsi
HTTP/1.1 404 Not Found
Apple-Failure-Reason: SWCERR00101 Bad HTTP Response: 404 Not Found
Cache-Control: max-age=3600,publicVotre propre serveur, tel que le CDN le voit
curl -v -A "AASA-Bot/1.0" https://links.example.com/.well-known/apple-app-site-associationLes codes SWCERR et comment les corriger
Apple ne publie pas de liste de ces codes. Ceux ci-dessous sont les messages que le CDN d’Apple renvoie dans l’en-tête Apple-Failure-Reason, chacun confirmé dans des fils des Apple Developer Forums ou par nos propres requêtes au CDN.
SWCERR00101 · Bad HTTP Response: 404 Not Found
Le CDN a demandé votre fichier et a reçu autre chose qu’un 200. Le plus souvent, le fichier se trouve sur le domaine racine alors que l’entitlement nomme un sous-domaine, ou l’inverse. Chaque hôte listé dans applinks: a besoin de son propre fichier à l’adresse https://<host>/.well-known/apple-app-site-association. Un 502 ici signifie que votre serveur d’origine était hors service quand Apple l’a interrogé.
SWCERR00201 · Insecure (non-https) redirects forbidden
L’URL du fichier redirige vers une adresse http://. Servez-le directement en HTTPS sur chaque domaine. La documentation d’Apple n’autorise aucune redirection ; dans nos tests, le CDN a suivi une redirection de https vers https, mais un retour vers http échoue à tous les coups.
SWCERR00202 · Connections to private/reserved IP addresses are not allowed
Le nom d’hôte pointe vers une adresse privée ou réservée, donc Apple ne s’y connecte pas. C’est typique des domaines de staging qui n’existent qu’à l’intérieur d’un VPN. Pour ceux-là, utilisez le mode développeur (voir plus bas), et un hôte public pour la production.
SWCERR00301 · Timeout
Le service d’Apple qui récupère le fichier a attendu sans recevoir le moindre en-tête. Les pare-feu, le géoblocage et les protections anti-bots qui soumettent les clients inconnus à une vérification en sont la cause habituelle. Apple indique que le fichier doit être accessible depuis n’importe quelle IP et ne publie pas ses plages d’adresses : ouvrez donc ce chemin à tout le monde.
SWCERR00302 · Network error (temporary)
Un échec temporaire, souvent lié au DNS. Si votre DNS va bien, cela se règle en général à la récupération suivante, qui, après un échec, a lieu dans l’heure.
SWCERR00303 · TLS error
Le certificat a expiré, a été émis pour un autre hôte, est auto-signé, ou la négociation TLS a échoué. Apple exige un certificat reconnu publiquement qui couvre le nom d’hôte exact. Un certificat pour example.com ne couvre pas links.example.com, sauf s’il le mentionne explicitement.
SWCERR00305 · Network error
Le CDN s’est connecté, mais le transfert a été interrompu : EOF, connection refused, ou gzip: invalid header quand le serveur annonce une compression qu’il n’envoie pas. Vérifiez les réglages du WAF et de la compression pour ce chemin précis.
SWCERR00401 · Bad JSON content
Le CDN a reçu autre chose que du JSON, généralement une page de vérification HTML ou une page de connexion. Le détail « invalid character ‘<’ » la trahit. La solution d’un ingénieur Apple sur les forums : faire en sorte que le serveur renvoie le fichier brut à n’importe quel user agent, AASA-Bot/* compris.
Vérifiez les chemins avec swcutil
Une fois qu’Apple a le fichier, reste à savoir si votre lien y correspond. Sur Mac, swcutil teste une copie locale du fichier avec une vraie URL : c’est la vérification que les ingénieurs d’Apple recommandent plutôt que le mode développeur.
Test de téléchargement
sudo swcutil dl -d links.example.comTest de correspondance
sudo swcutil verify -d links.example.com -j ./apple-app-site-association -u https://links.example.com/promoÀ quoi ressemble une correspondance
{ s = applinks, a = ABCD123.com.example.app, d = links.example.com }:
Pattern "https://links.example.com/promo" matched.Ce qu’en pense le téléphone lui-même
Avec le mode développeur activé, Réglages › Développeur › Universal Links propose un écran Diagnostics : saisissez une URL complète, et il vous dit si une app installée la revendique. Pour avoir toute l’histoire, faites un sysdiagnose et ouvrez swcutil_show.txt. Cherchez l’identifiant de votre app et lisez trois lignes.
Site/Fmwk Approval doit indiquer approved. Unspecified ou denied signifie que le téléphone n’a jamais reçu de fichier approuvé pour cette app et ce domaine : vérifiez l’entitlement, l’accès public et le préfixe du Team ID. User Approval indique si la personne a choisi le navigateur pour ce domaine. Last Checked et Next Check indiquent quand Apple a récupéré votre fichier pour la dernière fois.
Ce dernier point explique la plupart des moments « j’ai corrigé, mais rien n’a changé ». Après l’installation, un téléphone revérifie le fichier environ une fois par semaine. Pour tester une correction tout de suite, réinstallez l’app. Pour le staging, ajoutez ?mode=developer à l’entrée applinks : le CDN est contourné, mais seulement pour les builds signés en développement, sur les appareils où vous l’avez activé.
Les chiffres à retenir
- durée pendant laquelle le CDN d’Apple a gardé un fichier valide dans nos tests
- 6 h
- durée pendant laquelle il a gardé un échec
- 1 h
- fréquence à laquelle un iPhone revérifie après l’installation
- ~1 semaine
- attente minimale sur Android avant de consulter la vérification
- 20 s
durée pendant laquelle le CDN d’Apple a gardé un fichier valide dans nos tests
durée pendant laquelle il a gardé un échec
fréquence à laquelle un iPhone revérifie après l’installation
attente minimale sur Android avant de consulter la vérification
Android App Links : les états renvoyés par pm get-app-links
Sur Android, pas de CDN intermédiaire. Le vérificateur de l’appareil récupère lui-même https://<host>/.well-known/assetlinks.json, et depuis Android 12, un lien non vérifié n’affiche plus de sélecteur : il s’ouvre simplement dans le navigateur. Voilà pourquoi une empreinte manquante ressemble exactement à « le lien marche, mais pas dans mon app ».
Android 12 a aussi changé la façon dont plusieurs hôtes sont évalués. Chaque hôte est désormais vérifié séparément ; sous Android 11 et versions antérieures, un seul hôte en échec fait échouer tous les autres. Et sous Android 15, une modification d’assetlinks.json peut mettre jusqu’à sept jours à atteindre tous les appareils.
Relancez la vérification depuis votre ordinateur
Réinitialiser, vérifier, lire
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.appSortie typique
example.com: verified
sub.example.com: legacy_failure
example.org: 1026Ce que signifie chaque état
verified
Le domaine a passé la vérification. Si les liens ouvrent encore le navigateur, regardez l’intent filter : android:autoVerify="true", la catégorie BROWSABLE et les deux schémas, http et https.
none
Rien d’enregistré pour l’instant. Attendez quelques minutes et relancez verify-app-links.
legacy_failure
L’ancien vérificateur a rejeté le domaine sans dire pourquoi. Commencez par le fichier lui-même : HTTP 200, application/json, HTTPS, aucune redirection.
1024 et plus (par exemple 1026)
Une erreur propre au vérificateur. La documentation Android renvoie au réseau et à l’hébergement : les mêmes règles de 200, de JSON, de HTTPS et d’absence de redirection.
approved / denied
Imposé par une commande shell, pas par la vérification. Réinitialisez avec set-app-links avant de vous fier au moindre résultat.
migrated / restored / system_configured
Repris de l’ancienne vérification, restauré avec les données utilisateur ou défini par la configuration de l’appareil. Ce ne sont pas des erreurs, mais pas non plus la preuve que votre fichier fonctionne aujourd’hui.
L’empreinte juste sur votre ordinateur et fausse sur le Play Store
L’échec Android le plus courant n’a rien à voir avec l’hébergement. Avec Play App Signing, Google signe à nouveau votre app avec sa propre clé de signature d’app. Le SHA-256 que keytool vous donne pour votre clé d’importation n’est pas celui présent sur les téléphones des utilisateurs : le build de release échoue alors que votre build local passe.
Copiez plutôt l’empreinte depuis Play Console › Release › Setup › App signing. Le tableau sha256_cert_fingerprints accepte plusieurs valeurs : gardez-y aussi votre clé de debug, en majuscules. Et n’oubliez pas qu’une redirection de example.com vers www.example.com, ou de http vers https, signifie qu’Android ne vérifie aucun de vos liens.
Voyez ce que Google lit dans votre fichier
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"Vos campagnes tournent pendant la réparation
Des fichiers d’association cassés ne devraient pas vous coûter des installations. Un lien Appy envoie chaque téléphone vers le bon store sur toutes les offres, Huawei AppGallery compris, et sur Pro il essaie d’abord votre app : ceux qui l’ont déjà atterrissent directement dedans. Pas de fichier AASA, pas de SDK, pas de nouvelle version de l’app. Quand vos Universal Links refonctionnent, gardez le même lien Appy : les codes imprimés et les publications ne changent pas.
appy.to/yourapp
fonctionne pendant le débogage
- iPhoneVotre app sur Pro, ou l’App Store
- AndroidVotre app sur Pro, ou Google Play
- HuaweiAppGallery
- OrdinateurVotre site web
À lire ensuite
- Validateur de Universal LinksVérifie en une fois votre AASA sur votre serveur et sur le CDN d’Apple, ainsi que votre assetlinks.json.
- Générateur AASA et assetlinks.jsonRédige les deux fichiers à partir de votre Team ID, de votre bundle ID et de votre SHA-256.
- Les Universal Links ouvrent Safari au lieu de l’appLes causes liées au comportement, de la règle du même domaine au choix de l’utilisateur.
- Échec de la vérification des Android App LinksUn tour plus approfondi du côté Android.
Questions sur les codes d’erreur
Où voit-on les codes SWCERR ?
Dans l’en-tête Apple-Failure-Reason quand vous interrogez https://app-site-association.cdn-apple.com/a/v1/votre-domaine, dans la sortie de swcutil dl sur un Mac et dans le journal swcd sur un appareil.
Comment faire prendre en compte mon fichier AASA corrigé par Apple ?
Vous ne pouvez pas purger le CDN d’Apple. Il récupère à nouveau le fichier quand son cache expire, ce qui prenait une heure pour les échecs dans nos tests. Réinstallez ensuite l’app sur votre téléphone de test pour qu’il récupère la nouvelle copie au lieu d’attendre la vérification hebdomadaire.
La taille du fichier apple-app-site-association est-elle limitée ?
Apple a documenté une limite de 128 Ko en 2016. La documentation actuelle ne la reprend pas, mais un fichier léger vous évite la question.
Pourquoi mon lien ouvre-t-il le navigateur quand je le tape dans Safari ?
C’est normal. Les URL tapées et les liens à l’intérieur d’un même domaine restent dans le navigateur, par conception. Testez plutôt depuis Notes ou Messages.
Que signifie legacy_failure sur Android ?
L’ancien vérificateur a rejeté le domaine et Android ne dit pas pourquoi. Vérifiez que assetlinks.json renvoie un 200 en application/json, en HTTPS et sans redirection, et qu’il contient l’empreinte de Play App Signing.
Puis-je éviter tout cela ?
En partie. Sur l’offre Pro, un lien Appy essaie d’abord le schéma d’URL de votre app, puis se rabat sur le bon store : il fonctionne donc sans fichier AASA sur votre propre domaine. De vrais Universal Links demandent toujours la configuration décrite plus haut.
Existe-t-il un outil qui vérifie tout cela d’un coup ?
Oui. Le validateur de Universal Links d’Appy est gratuit et ne demande aucune inscription. Il vérifie votre fichier AASA sur votre serveur et sur le CDN d’Apple, ainsi que votre assetlinks.json via l’API Digital Asset Links de Google, puis vous dit quoi corriger.
Continuer à explorer
App Links Android non vérifiés : le diagnostic en cinq minutes avec adb
Depuis Android 12, un App Link dont la vérification de domaine échoue s’ouvre dans le navigateur au lieu de votre app — en silence, et pas sur tous les appareils. La checklist adb qui trouve la cause vite.
Universal Links ouvrent Safari ? Corrigez AASA, App Links, redirections et headers
Workflow pratique pour corriger les universal links et app links qui ouvrent le navigateur au lieu de l’app.
Comment les navigateurs in-app gèrent les deep links : Instagram, TikTok, Facebook, Gmail, Telegram et les autres
Votre lien ouvre l’app depuis Safari mais pas dans Instagram. Ce que font les navigateurs in-app d’Instagram, TikTok, Facebook, Gmail, Telegram et d’autres, les règles iOS et Android, et comment prévoir un repli.
Vous cherchez autre chose ? Parcourez tous les sujets sur le blog.
Ne perdez plus de clics sur des liens cassés
Trouvez le fichier fautif avec le validateur gratuit, et gardez toutes vos campagnes actives en attendant grâce à un lien Appy : le bon store sur toutes les offres, votre app sur Pro.