Erreurs et limites

L’enveloppe d’erreur

Toute erreur de l’API a la même forme, quel que soit le statut :

{
  "error": {
    "code": "INVALID_FIELD",
    "message": "startAt : date invalide (ISO 8601 attendu).",
    "requestId": "32a8203e-cf4d-454b-afa4-b5c565b3e584",
    "details": [
      { "field": "startAt", "message": "date invalide (ISO 8601 attendu)." }
    ],
    "meta": { }
  }
}

• code est stable : testez-le dans votre code. Les codes propres à une route sont listés dans la référence, avec le cas qui les produit.
• message est en français, écrit pour être montré tel quel à l’utilisateur de votre service. Ne le testez pas : il peut être reformulé.
• requestId identifie l’appel. Il est aussi dans l’en-tête X-Request-ID de toute réponse. Donnez-le au support Treats pour toute question sur un appel.
• details liste les champs refusés, un par ligne, sur les erreurs de validation.
• meta porte des informations propres à l’erreur : la raison d’un créneau refusé, l’identifiant d’un doublon…

Une erreur interne (500 INTERNAL_ERROR) ne dit jamais sa cause ; son requestId suffit à Treats pour la retrouver.

Codes communs à toutes les routes

Statut	Code	Cas	Que faire
400	INVALID_FIELD	Un champ ou un paramètre est invalide, ou inconnu de la route.	Corriger l’appel d’après details.
400	INVALID_BODY	Le corps n’est pas un JSON lisible.	Corriger l’appel.
400	BODY_REQUIRED	La route attend un corps et n’en a reçu aucun.	Envoyer le corps.
400	SITE_ID_REQUIRED	Écriture sans site alors que plusieurs sites sont ouverts.	Passer site_id ou Treats-Site-Id.
400	INVALID_SITE_ID	site_id n’est pas un identifiant valide.	Corriger l’appel.
400	IDEMPOTENCY_KEY_REQUIRED	POST sans Idempotency-Key.	Ajouter une clé unique par opération.
400	IDEMPOTENCY_KEY_TOO_LONG	Clé de plus de 255 caractères.	Utiliser un UUID.
401	UNAUTHORIZED, INVALID_TOKEN	Jeton absent, inconnu ou expiré, autorisation retirée, application suspendue.	Redemander un jeton une fois ; si la demande est refusée, l’organisation vous a déconnecté.
403	SCOPE_MISSING	Le droit de la route n’est pas accordé.	Demander le droit à l’organisation, ou ne pas appeler la route.
404	…_NOT_FOUND, NOT_FOUND	Ressource inconnue, hors des sites ouverts, ou route inconnue.	Ne pas réessayer.
409	IDEMPOTENCY_IN_PROGRESS	Le premier envoi avec cette clé est encore en cours.	Réessayer une seconde plus tard avec la même clé.
422	IDEMPOTENCY_KEY_REUSED	Clé déjà utilisée pour un autre corps.	Une nouvelle clé par opération.
429	RATE_LIMITED	Quota dépassé.	Attendre Retry-After secondes.
500	INTERNAL_ERROR	Erreur chez Treats.	Réessayer plus tard avec la même Idempotency-Key ; si elle persiste, écrire au support avec le requestId.
503	UNAVAILABLE	Service momentanément indisponible (moteur de recherche…).	Réessayer plus tard.

Quota d’appels

Chaque autorisation (votre application dans une organisation) dispose de 300 appels par minute. Chaque réponse porte :

• RateLimit-Limit : le quota de la minute ;
• RateLimit-Remaining : les appels restants ;
• RateLimit-Reset : les secondes avant le prochain quota.

Au-delà, l’appel répond 429 RATE_LIMITED avec Retry-After. Attendez ce délai avant de réessayer ; ne réessayez pas en boucle.

Les demandes de jeton ont leur propre limite : 60 par minute et par adresse IP, 30 par minute et par application. Un jeton vaut une heure, gardez-le.

Réessayer sans risque

• Une lecture (GET) se réessaie toujours.
• Un POST se réessaie avec la même Idempotency-Key : s’il avait abouti, vous recevez sa réponse d’origine, sans double écriture.
• PATCH et PUT donnent le même résultat quand on les répète.
• Réessayez sur un 429, un 5xx ou une coupure réseau, avec une attente croissante (1 s, 2 s, 4 s…). Ne réessayez pas un 4xx autre que 409 IDEMPOTENCY_IN_PROGRESS et 429 : l’appel est refusé tel qu’il est.

Erreurs de la demande de jeton

POST /oauth/token répond au format OAuth 2, que les bibliothèques OAuth savent lire :

{
  "error": "unauthorized_client",
  "error_description": "Cette organisation n'a pas connecté l'application.",
  "treats_code": "NO_GRANT"
}

error	Cas
invalid_request	Paramètre absent ou illisible (organization_id compris).
unsupported_grant_type	Autre flux que client_credentials.
invalid_client	Identifiant ou secret faux, secret retiré, application suspendue.
unauthorized_client	L’organisation n’a pas connecté votre application, ou l’a déconnectée.
slow_down	Trop de demandes de jeton (429).

Support

Écrivez à partenaires@treats.vet avec le requestId, l’heure de l’appel et l’organisation concernée. Le journal de chaque appel est conservé 90 jours.