Documentation Limites et erreurs
Limites et erreurs
Les erreurs
Une erreur répond au format standard RFC 9457 (application/problem+json), avec un message
en français lisible tel quel :
{
"type": "https://heyalink.com/developpeurs/api/emploi#erreur-422",
"title": "Annonce refusée",
"status": 422,
"detail": "Le champ titre est obligatoire.",
"instance": "/api/emploi/v1/offres/CC-2026-014",
"errors": { "titre": ["Le champ titre est obligatoire."] },
"violations": [
{
"champ": "titre",
"regle": "required",
"message": "Le champ titre est obligatoire.",
"exemple": "Chef de chantier gros œuvre"
}
]
}
violations dit, pour chaque champ refusé, la règle qui a échoué et une valeur valide : de quoi
corriger sans chercher.
| Code | Signification | Que faire |
|---|---|---|
| 200, 201 | modifiée, créée | rien |
| 204 | retirée | rien |
| 304 | rien n'a changé depuis votre ETag |
garder ce que vous avez |
| 400 | requête mal formée (Idempotency-Key trop longue, par exemple) |
lire detail |
| 401 | clé absente, inconnue, révoquée ou expirée | vérifier l'en-tête, recréer une clé |
| 403 | clé de l'API Formation, page sans la formule Grands comptes, droit manquant, adresse IP non autorisée, ou domaine pas encore prouvé | lire detail |
| 404 | référence inconnue (lecture seulement) | vérifier la référence |
| 409 | la même Idempotency-Key est encore en cours |
attendre sa réponse |
| 422 | offre refusée : champ manquant ou trop long, lien bloqué, offre retirée par la modération, ou Idempotency-Key déjà prise |
lire errors, champ par champ |
| 429 | trop d'appels | attendre Retry-After secondes, ou passer par /lot |
Erreur 400
La requête est mal formée : lisez detail, il dit quoi corriger.
Erreur 401
La clé est absente, mal copiée, révoquée ou expirée. Vérifiez l'en-tête
Authorization: Bearer hl_emploi_live_… ; au besoin, créez une nouvelle clé sur l'écran API
Emploi.
Erreur 403
detail dit laquelle de ces raisons s'applique : la clé appartient à l'API Formation (elle
n'ouvre pas l'API Emploi) ; la page n'a pas, ou plus, la formule Grands comptes ; la clé n'a pas le droit
demandé (par exemple offres:ecriture) ; l'appel vient d'une adresse IP que la clé n'autorise
pas ; ou la page n'a pas encore prouvé son domaine (publication pour de bon).
Erreur 404
La référence n'existe pas pour votre page. Vérifiez-la ; un PUT la crée.
Erreur 409
Une requête avec la même Idempotency-Key est encore en cours : attendez sa réponse avant de
rejouer.
Erreur 422
L'offre est refusée : errors donne le message champ par champ. Corrigez puis renvoyez.
Erreur 429
Trop d'appels pour cette clé. Attendez le nombre de secondes donné par Retry-After, ou
regroupez vos offres avec /lot (100 par appel).
Une offre masquée par la modération de Heyalink le reste : la republier répond 422, et son
etat vaut masquee_par_la_moderation.
Le journal
GET /journal rend les 100 derniers appels et lectures de sources de l'API Emploi, avec leur
statut et leur message : une clé ne lit que le journal de son API. Il se lit avec une clé qui a
le droit offres:ecriture. Le même journal se lit sur l'écran API Emploi. Il est gardé 90
jours ; le journal de test (requêtes et réponses des clés d'essai, secrets masqués) l'est 7
jours.
curl "https://heyalink.com/api/emploi/v1/journal" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"
Retirer une offre se rejoue sans risque : la réponse est 204, même si elle était déjà retirée.
curl -X DELETE "https://heyalink.com/api/emploi/v1/offres/MAC-2026-002" \
-H "Authorization: Bearer hl_emploi_live_VOTRECLE"