Codes d'erreur et structure des réponses d'erreur

Comprendre les erreurs de l'API Diamond Careers, leur format et les actions à prendre.

L'API retourne des erreurs HTTP standard accompagnées d'un corps JSON structuré.

Format standard

{
  "code": "rest_invalid_param",
  "message": "Le champ 'email' est invalide.",
  "data": {
    "status": 400,
    "params": {
      "email": "L'adresse email fournie n'est pas au bon format."
    }
  }
}

code — identifiant court et stable de l'erreur. C'est ce sur quoi vous devez piloter votre logique.
message — texte en français destiné à l'affichage. Peut être reformulé entre versions.
data — objet complémentaire. data.status reflète le code HTTP. Selon le cas, d'autres champs (params, existing_application_id, etc.) précisent l'erreur.

Codes HTTP

2xx — Succès

Code	Sens
200 OK	Requête réussie, corps avec la réponse
201 Created	Ressource créée
204 No Content	Succès sans corps (souvent après `DELETE`)

4xx — Erreurs client

Code	Sens	Action recommandée
400 Bad Request	Requête mal formée (JSON invalide, paramètre manquant)	Vérifiez la structure
401 Unauthorized	Authentification absente ou invalide	Vérifiez votre jeton, régénérez-le
403 Forbidden	Authentifié mais hors de votre périmètre ou rôle insuffisant	Vérifiez la maison ciblée et votre rôle
404 Not Found	Ressource introuvable	Vérifiez l'identifiant
409 Conflict	Conflit métier (ex. doublon)	Vérifiez l'état actuel avant de réessayer
422 Unprocessable Entity	Données valides syntaxiquement mais invalides métier	Lisez `data` pour le détail
429 Too Many Requests	Limite de débit dépassée	Voir Rate limits

5xx — Erreurs serveur

Code	Sens	Action recommandée
500 Internal Server Error	Erreur inattendue	Réessayez une fois ; si persistant, support
502 Bad Gateway	Passerelle injoignable	Backoff exponentiel
503 Service Unavailable	Maintenance	Patientez, vérifiez status.diamondcareers.fr
504 Gateway Timeout	Délai de réponse dépassé	Backoff exponentiel

Codes d'erreur métier fréquents

Authentification

Code	Sens
`invalid_credentials`	Identifiants incorrects au login
`jwt_invalid_token`	Jeton invalide ou mal formé
`jwt_expired_token`	Jeton expiré
`jwt_no_auth_header`	En-tête `Authorization` absent
`forbidden`	Authentifié mais sans permission sur cette ressource

Validation des paramètres

Code	Sens
`invalid_param`	Un ou plusieurs paramètres ne respectent pas le format. `data.params` détaille
`missing_param`	Paramètre obligatoire absent
`invalid_field`	Champ envoyé non reconnu pour cette ressource

Ressources et conflits

Code	Sens
`not_found`	Identifiant invalide ou hors de votre périmètre
`already_applied`	Une candidature existe déjà pour cette offre et ce candidat
`invalid_status_transition`	Transition de statut non autorisée (ex. repasser une candidature acceptée à pending)
`last_owner`	Action bloquée car vous êtes le dernier `owner` de l'établissement

Limites et abus

Code	Sens
`too_many_requests`	Limite de débit dépassée
`upload_too_large`	Fichier au-delà de la taille maximale
`upload_unknown_error`	Erreur inattendue lors du téléversement

Exemples

Validation de paramètre

{
  "code": "invalid_param",
  "message": "Le champ 'maison_id' est requis.",
  "data": {
    "status": 400,
    "params": {
      "maison_id": "Champ obligatoire manquant."
    }
  }
}

Candidature en doublon

{
  "code": "already_applied",
  "message": "Une candidature existe déjà pour cette offre.",
  "data": {
    "status": 409,
    "existing_application_id": 18472
  }
}

Jeton expiré

{
  "code": "jwt_expired_token",
  "message": "Le jeton est expiré. Régénérez-en un nouveau.",
  "data": {
    "status": 401
  }
}

Bonnes pratiques côté intégration

Pilotez votre logique sur code, pas sur message. Les codes sont stables, les messages peuvent évoluer.

Backoff exponentiel sur 5xx. 1 s, puis 2, 4, 8… plafonné à 30 secondes.

Distinguez récupérable et définitif. 4xx (sauf 429) : généralement définitif. 5xx : presque toujours récupérable. 429 : respectez Retry-After.

Loguez avec contexte. En cas de souci, notre support a besoin du code, du message, du timestamp UTC, du chemin appelé et du payload envoyé. Conservez ces traces quelques jours.

Affichez les messages aux utilisateurs avec discernement. Le champ message est rédigé pour l'affichage ; vous pouvez le passer tel quel à un utilisateur final, ou le traduire dans votre propre formulation.

Codes d'erreur et structure des réponses d'erreur

On this page