Erreurs

L’API utilise les codes de statut HTTP conventionnels et renvoie une enveloppe d’erreur structurée à chaque échec, afin que vous puissiez vous appuyer sur des champs lisibles par une machine plutôt que d’analyser du texte.

Enveloppe d’erreur

{
  "error": {
    "type": "invalid_request_error",
    "code": "bad_request",
    "message": "limit must be a positive integer.",
    "param": "limit",
    "doc_url": "https://docs.useservice.app/api/errors#bad_request"
  }
}

Champ	Description
`type`	Catégorie générale de l’erreur (voir ci-dessous). Toujours présent.
`code`	Un code machine spécifique et stable identifiant l’échec. Toujours présent.
`message`	Une explication lisible par un humain. Destinée à la journalisation et au débogage — ne l’affichez pas directement aux utilisateurs finaux et ne vous appuyez pas dessus pour brancher votre logique.
`param`	Le paramètre de requête en cause — présent uniquement lorsqu’un paramètre précis a causé l’erreur (par exemple une valeur `limit`, `status` ou `expand` invalide). Omis sinon (il n’est pas envoyé à `null`).
`doc_url`	Un lien direct vers l’entrée de référence de ce `code` (`https://docs.useservice.app/api/errors#<code>`). Toujours présent.

Chaque réponse — succès comme erreurs — renvoie également l’en-tête Service-Version qui l’a servie.

Types d’erreur

`type`	Signification
`invalid_request_error`	La requête était mal formée — un paramètre, une valeur ou un filtre incorrect.
`authentication_error`	La clé d’API est manquante, mal formée ou invalide.
`rate_limit_error`	Vous avez dépassé la limite de débit.
`api_error`	Une erreur inattendue de notre côté. Vous pouvez réessayer avec un délai exponentiel.

Catalogue des codes d’erreur

Tous les code que l’API peut renvoyer, avec leur type, leur statut HTTP et le contexte dans lequel ils surviennent. Branchez votre logique sur code pour un traitement précis ; repliez-vous sur type pour les catégories générales. Le doc_url de chaque erreur renvoie directement vers son entrée ci-dessous (https://docs.useservice.app/api/errors#<code>).

`code`	`type`	HTTP	Quand il survient
`auth_header_missing`	`authentication_error`	`401`	Aucun en-tête `Authorization: Bearer …` n’a été envoyé.
`invalid_token`	`authentication_error`	`401`	La clé d’API est invalide, révoquée, expirée ou inconnue.
`bad_request`	`invalid_request_error`	`400`	Un paramètre de requête, un filtre, un curseur, `expand` ou une valeur `Service-Version` est mal formé. L’entrée fautive est nommée dans `param`.
`not_found`	`invalid_request_error`	`404`	La ressource n’existe pas pour le restaurant de cette clé (voir ci-dessous).
`rate_limited`	`rate_limit_error`	`429`	Vous avez dépassé la limite de débit. Respectez `Retry-After`.
`internal_error`	`api_error`	`500`	Une erreur inattendue de notre côté. Vous pouvez réessayer avec un délai exponentiel.

`auth_header_missing`

authentication_error · 401 Unauthorized. Aucun en-tête Authorization: Bearer … n’a été envoyé. Ajoutez l’en-tête — voir Authentification.

`invalid_token`

authentication_error · 401 Unauthorized. Une clé a été fournie mais elle est invalide, révoquée, expirée ou inconnue. Demandez une nouvelle clé si la vôtre ne fonctionne plus.

`bad_request`

invalid_request_error · 400 Bad Request. Un paramètre de requête, un filtre, un curseur de pagination, expand ou une valeur Service-Version est mal formé. L’entrée fautive est nommée dans param. Corrigez la requête — la réessayer telle quelle échouera de la même manière.

`not_found`

invalid_request_error · 404 Not Found. La ressource n’existe pas pour le restaurant de cette clé. Voir 404, et non 403, entre restaurants.

`rate_limited`

rate_limit_error · 429 Too Many Requests. Vous avez dépassé la limite de débit. Attendez l’intervalle Retry-After, puis réessayez — voir Limites de débit.

`internal_error`

api_error · 500. Une erreur inattendue de notre côté. Vous pouvez réessayer avec un délai exponentiel ; contactez le support si le problème persiste.

Codes de statut HTTP

Statut	Signification
`200 OK`	La requête a réussi.
`304 Not Modified`	Renvoyé sur un `GET` conditionnel lorsque votre `If-None-Match` correspond. Voir Étendre les objets pour la mise en cache.
`400 Bad Request`	Une requête mal formée — un paramètre ou une valeur incorrect. Vérifiez `param`.
`401 Unauthorized`	Clé d’API manquante ou invalide. Voir Authentification.
`404 Not Found`	La ressource n’existe pas pour le restaurant de cette clé.
`429 Too Many Requests`	Débit limité. Voir Limites de débit.
`500` / `503`	Un problème est survenu de notre côté. Réessayez avec un délai exponentiel.

404, et non 403, entre restaurants

Si vous demandez une ressource qui existe mais appartient à un autre restaurant, l’API renvoie 404 Not Found, et non 403 Forbidden. Du point de vue de votre clé, la ressource n’existe tout simplement pas. Cela évite de divulguer l’existence des données d’autres restaurants. Un identifiant valide qui devrait « fonctionner » selon vous mais qui renvoie 404 signifie presque toujours qu’il appartient à un restaurant différent (ou à une autre clé).

Gérer les erreurs

Branchez votre logique sur type et code, jamais sur message.
Ne réessayez que les 429 (après Retry-After) et les 5xx (avec un délai exponentiel).
Ne réessayez jamais les 400/401/404 — ils échoueront de nouveau tant que vous ne modifiez pas la requête ou la clé.