Gestion des erreurs

Format des erreurs

Toutes les erreurs retournent un objet JSON avec un champ message. Certaines ajoutent un code stable, à utiliser plutôt que le texte du message :

{
  "message": "Description de l'erreur",
  "code": "PERMISSION_REQUIRED"
}

Codes HTTP

Code	Signification	Quand
200	OK	Requête réussie
201	Created	Ressource créée (ex: rendez-vous)
400	Bad Request	Requête invalide (champs manquants, format incorrect)
401	Unauthorized	Clé API manquante, invalide, expirée ou révoquée
403	Forbidden	Permission manquante sur la clé
404	Not Found	Ressource introuvable
409	Conflict	Conflit avec l’état de la ressource
429	Too Many Requests	Limite de requêtes depassee
500	Internal Server Error	Erreur serveur (corps {"message": "Internal server error", "requestId": "..."}, même identifiant dans l’en-tête X-Request-ID)

Exemples

401 - Clé invalide

curl -H "X-API-Key: vk_cle_invalide" \
  https://app.treats.vet/api/v1/patients

{
  "message": "Authentication required"
}

Une clé inconnue, expirée ou révoquée reçoit la même réponse qu’une requête sans clé.

403 - Permission manquante

Votre clé a PATIENT_READ mais pas CLIENT_READ :

curl -H "X-API-Key: vk_votre_cle" \
  https://app.treats.vet/api/v1/clients

{
  "message": "Insufficient permissions",
  "code": "PERMISSION_REQUIRED"
}

404 - Ressource introuvable

curl -H "X-API-Key: vk_votre_cle" \
  https://app.treats.vet/api/v1/patients/00000000-0000-0000-0000-000000000000

{
  "message": "Patient not found: 00000000-0000-0000-0000-000000000000"
}

Une ressource d’une autre clinique répond aussi 404, jamais 403.

429 - Rate limit

{
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 42
}

Headers :

Retry-After: 42
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

Conseils