Aller au contenu principal

FAQ, erreurs fréquentes et conseils pratiques

Repères utiles
remarque

Cette note regroupe les questions et pièges les plus probables quand on suit ce wiki de manière progressive.

Questions fréquentes​

Faut-il lire tous les chapitres ?​

Non.

Le wiki est structuré pour être progressif, mais tu peux choisir un parcours selon ton objectif. Pour ça, commence par :

Pourquoi API de base est-il si important ?​

Parce que presque tout le reste s’appuie dessus :

  • auth,
  • relations SQL,
  • erreurs,
  • middleware,
  • tests,
  • Docker,
  • notifications,
  • Celery,
  • frontend.

Si API de base n’est pas clair, les chapitres avancés vont te sembler artificiels ou trop lourds.

Est-ce grave si je ne fais pas le frontend React ?​

Non.

Le frontend est un bonus. Le cœur du wiki reste backend-first. Tu peux apprendre énormément sur FastAPI sans faire le chapitre React.

Pourquoi la route /user/token n’accepte pas simplement du JSON ?​

Parce que dans ce wiki, elle est branchée sur OAuth2PasswordRequestForm. Donc elle attend un corps compatible :

  • application/x-www-form-urlencoded

C’est pour cela que le frontend React doit utiliser :

  • URLSearchParams

et pas un simple JSON.stringify().

Pourquoi le login peut-il échouer alors que l’email et le mot de passe sont corrects ?​

Parce que l’utilisateur peut être :

  • non vérifié,
  • mal chargé,
  • ou son token/l’état peut être incohérent.

Le cas le plus fréquent dans ce wiki est :

  • email_verified = False

Dans ce cas, c’est normal que la connexion soit refusée tant que l’email n’a pas été validé.

Pourquoi le reset password répond toujours avec un message générique ?​

Pour éviter de révéler si un compte existe ou non.

C’est une petite mesure simple, mais très utile contre l’énumération de comptes.

Pourquoi avoir d’abord utilisé BackgroundTasks, puis Celery ?​

Parce que c’est le chemin pédagogique le plus clair.

BackgroundTasks​

Bien pour :

  • comprendre le flux,
  • commencer simplement,
  • éviter d’introduire Redis et worker trop tôt.

Celery​

Bien pour :

  • rendre les jobs plus robustes,
  • sortir le travail du process FastAPI,
  • monter en charge plus proprement.

Le wiki montre volontairement cette progression.

Pourquoi Docker arrive après les tests ?​

Parce que Docker emballe une application.

Si l’application n’est pas encore suffisamment claire et testable, dockeriser trop tôt risque surtout de masquer les problèmes au lieu de les clarifier.

Pourquoi le frontend React demande du CORS côté FastAPI ?​

Parce que dans le navigateur :

  • frontend et backend tournent sur des origines différentes,
  • par exemple localhost:5173 et localhost:8000.

Sans CORSMiddleware, les requêtes seront bloquées par le navigateur.

Erreurs fréquentes​

Erreur fréquente — CORS bloque tout​

Symptôme​

Le frontend n’arrive pas à appeler l’API depuis le navigateur.

Cause fréquente​

CORSMiddleware absent ou origine oubliée.

Réflexe​

Vérifie d’abord :

C’est le chapitre qui centralise l’ajout de CORSMiddleware, le contrat frontend/backend et les appels navigateur.

Erreur fréquente — 401 Unauthorized​

Symptôme​

Les routes protégées refusent l’accès.

Causes fréquentes​

  • token absent,
  • token expiré,
  • header Authorization non injecté,
  • utilisateur non trouvé,
  • email non vérifié.

Réflexe​

Vérifie d’abord :

Erreur fréquente — 422 Unprocessable Entity​

Symptôme​

La route reçoit bien la requête, mais refuse les données.

Causes fréquentes​

  • mauvais nom de champ,
  • JSON au lieu de form-encoded,
  • schéma incomplet,
  • type inattendu.

Réflexe​

Compare précisément :

  • le schéma FastAPI attendu,
  • le payload réellement envoyé.

Reviens surtout à :

Erreur fréquente — les tâches ne s’affichent pas côté frontend​

Symptôme​

Le dashboard est vide alors que les données existent.

Causes fréquentes​

  • appel du mauvais endpoint,
  • token non injecté,
  • oubli de queryKey ou d’invalidation React Query,
  • utilisateur connecté différent.

Réflexe​

Revalide :

  • /task/mine
  • le token frontend
  • la session utilisateur réellement active

Erreur fréquente — le worker Celery ne fait rien​

Symptôme​

L’API répond, mais les mails/SMS ne partent pas.

Causes fréquentes​

  • worker non lancé,
  • Redis non disponible,
  • mauvais REDIS_HOST ou REDIS_PORT,
  • mauvais chemin -A pour Celery.

Réflexe​

Reviens à :

Erreur fréquente — token de vérification ou de reset invalide​

Symptôme​

Le lien reçu par email ne fonctionne pas.

Causes fréquentes​

  • token expiré,
  • mauvais salt,
  • secret changé,
  • URL coupée ou mal copiée.

Réflexe​

Vérifie :

  • la génération du token,
  • la lecture du token,
  • la cohérence du salt,
  • l’expiration attendue.

Le meilleur chapitre à relire est :

Et si le doute porte sur l’utilisateur ou l’état de connexion autour du flow, reviens aussi à :

Conseils pratiques​

Conseil pratique — ne confonds pas les responsabilités​

Le backend doit porter :​

  • validation,
  • auth,
  • sécurité,
  • règles métier,
  • accès DB,
  • jobs asynchrones.

Le frontend doit porter :​

  • navigation,
  • état d’interface,
  • formulaires,
  • expérience utilisateur,
  • appels API correctement branchés.

Cette séparation aide énormément à garder le projet lisible.

Conseil pratique — ne complexifie pas tout dès le début​

Le wiki montre une progression utile :

  • base simple,
  • puis auth,
  • puis données,
  • puis robustesse,
  • puis packaging,
  • puis communication utilisateur,
  • puis async,
  • puis frontend bonus.

Si tu essaies de tout faire en même temps, tu risques surtout de perdre la logique d’ensemble.

Conseil pratique — quand tu bloques, reviens au dernier état stable​

Exemple :

  • si Celery te bloque, reviens au chapitre notifications simple,
  • si React te bloque, reviens aux tests d’API backend,
  • si auth te bloque, reviens à API de base puis auth.

C’est souvent la manière la plus rapide d’avancer proprement.

Résumé rapide​

Le plus important à retenir est simple :

  • les erreurs les plus pénibles viennent souvent d’une couche mal comprise,
  • le wiki est justement là pour les séparer,
  • et cette note sert à t’aider à retrouver rapidement le bon chapitre quand ça coince.

Si tu ne sais plus dans quel ordre reprendre, reviens à Parcours de lecture.