FAQ développeur

Authentification

Pourquoi je reçois `401 Unauthorized` ?

Causes typiques :

Token expiré (durée : 15 min) — refresh
Token révoqué par logout
Mauvaise env (token prod sur staging)
Header mal formé : Bearer<espace>TOKEN

Pourquoi `403 Forbidden` même avec un token valide ?

Rôle insuffisant. Consulter Rôles & permissions :

Comment fonctionne la rotation refresh ?

Chaque POST /auth/refresh-token renvoie un nouveau refresh token et invalide l’ancien. Voir JWT refresh.

Rate limiting

Pourquoi `429 Too Many Requests` ?

Limites par endpoint, voir Rate limiting. Respecter le header Retry-After.

Comment éviter le rate limit ?

Cache local agressif (30 s) pour les recherches publiques
Pagination large (size=50 max) pour réduire le nombre d’appels
Webhooks (quand disponibles) ou polling ≥ 60 s

Uploads

Pourquoi `413 Payload Too Large` ?

Taille max dépend du type — voir Uploads médias :

Type	Max
Logo	2 Mo
Bannière	5 Mo
Photo profil	1 Mo
CV	5 Mo
KYC	10 Mo

Pourquoi `415 Unsupported Media Type` ?

MIME type non autorisé. Vérifier que :

Le fichier a bien la bonne extension
Le MIME détecté par le backend (file --mime-type) correspond à l’extension
Envoyer en multipart/form-data (pas en JSON base64)

Pourquoi `422` après upload ?

Recherche

Ma recherche full-text ne retourne rien

Vérifier q=mot+complet (espaces → + ou %20)
Essayer des variantes : dev, developer, développeur
Le ranking est pondéré — voir FTS
Retirer les filtres (typeContrat, villeId) un à un

Comment trier les résultats ?

GET /v1/api/offres/search?q=java&sort=pertinence    # défaut
GET /v1/api/offres/search?q=java&sort=dateRecent
GET /v1/api/offres/search?q=java&sort=salaireDesc

Environnements

Mon code staging ne marche pas en prod

Vérifier :

base_url différente (voir Environnements)
CORS : staging accepte localhost, prod non
Quotas plus stricts en prod
Comptes staging ne sont pas migrés en prod

Comment tester sans compte réel ?

Un compte demo@wethehivers.com avec rôle CANDIDAT existe sur staging uniquement. Demander le mot de passe à l’équipe tech.

SDK / Types

Où trouver les types TypeScript / Java / Python ?

Générer depuis openapi.json : Détails : Snippets JS, Java, Python.

Un SDK officiel est-il prévu ?

Non à court terme. La génération depuis OpenAPI couvre les besoins avec 0 maintenance côté backend.

Collections

Postman / Insomnia / Bruno ?

Toutes disponibles — voir Collections API. Mises à jour automatiquement à chaque push backend (CI GitLab).

Mes variables d’environnement ne se remplissent pas

Les collections fournissent un script post-login qui stocke access_token / refresh_token dans l’environnement actif. Vérifier :

L’environnement est bien sélectionné (pas “No Environment”)
Le script est bien au niveau collection pour Postman
Bruno : bru.setEnvVar dans script:post-response

Production

Comment monitorer mon intégration ?

Logguer X-Request-Id renvoyé par chaque réponse (corrélation avec les logs backend)
Tracer les codes 4xx/5xx dans Sentry / DataDog
Alerter sur taux d’erreur > 1% sur 5 min
Dashboard uptime externe (UptimeRobot, Pingdom)

Cache : quoi, quand, combien ?

Ressource	TTL recommandé	Stratégie
`/offres/search` (public)	30 s	Par clé (query + filtres)
`/offres/{slug}`	5 min	Par slug
`/regions`, `/villes`, `/categories`	24 h	Global
`/candidats/me/*`	0	Pas de cache

Comment rafraîchir après publication d’une offre ?

Backend purge CDN + invalide cache interne à chaque publish. Côté client :

Revalider après une action qui modifie les données
Pour SSR / SSG : utiliser stale-while-revalidate

Sécurité

Dois-je stocker le refresh token en localStorage ?

⚠️ À éviter en prod. Recommandations : localStorage reste acceptable pour le access token court (15 min) puisque le risque XSS est temporellement limité.

CORS : mes requêtes sont bloquées

Les origines whitelistées sont :

https://wethehivers.com (candidat)
https://recruteur.wethehivers.com
https://staging.wethehivers.com (staging)
http://localhost:3000 / :3001 (dev uniquement)

Toute autre origine → bloquée. Pour un proxy serveur-à-serveur, CORS ne s’applique pas.

Contact & support

Canal	Usage
Email tech	`tech@wethehivers.com`
GitLab issues	Bugs reproductibles
Discord Dev	Questions rapides (invitation sur demande)
Pager astreinte	Incidents prod uniquement — via email

​FAQ développeur

​Authentification

​Pourquoi je reçois 401 Unauthorized ?

​Pourquoi 403 Forbidden même avec un token valide ?

​Comment fonctionne la rotation refresh ?

​Rate limiting

​Pourquoi 429 Too Many Requests ?

​Comment éviter le rate limit ?

​Uploads

​Pourquoi 413 Payload Too Large ?

​Pourquoi 415 Unsupported Media Type ?

​Pourquoi 422 après upload ?

​Recherche

​Ma recherche full-text ne retourne rien

​Comment trier les résultats ?

​Environnements

​Mon code staging ne marche pas en prod

​Comment tester sans compte réel ?

​SDK / Types

​Où trouver les types TypeScript / Java / Python ?

​Un SDK officiel est-il prévu ?

​Collections

​Postman / Insomnia / Bruno ?

​Mes variables d’environnement ne se remplissent pas

​Production

​Comment monitorer mon intégration ?

​Cache : quoi, quand, combien ?

​Comment rafraîchir après publication d’une offre ?

​Sécurité

​Dois-je stocker le refresh token en localStorage ?

​CORS : mes requêtes sont bloquées

​Contact & support

​Voir aussi