Guides

Erreurs

Les erreurs suivent le format standard RFC 9457 (application/problem+json). Seul l'endpoint /oauth/token utilise le format OAuth2 (voir Authentification).

Format

réponse

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://o-ven.com/developers/errors#invalid_parameter",
  "title": "Paramètre invalide",
  "status": 400,
  "detail": "La fenêtre `from` / `to` ne peut pas dépasser 93 jours.",
  "request_id": "req_9d2e41c0a7b34f5e8c1d6a2b3f4e5d6c"
}

type : URL de la documentation du code d'erreur (cette page). Le fragment après # est le code, stable : c'est lui qu'il faut tester dans votre programme.
title : libellé court, lisible.
status : statut HTTP, identique à celui de la réponse.
detail : explication propre à cette occurrence (paramètre en cause…). Optionnel, destiné à un humain : ne le parsez pas.
request_id : identifiant de l'appel, également renvoyé dans l'en-tête X-Request-Id de toutes les réponses. Communiquez-le au support.

Codes d'erreur

400invalid_parameterParamètre invalide

Cause. Un paramètre est absent, mal formé ou incohérent : date sans fuseau, to antérieur à from, fenêtre de plus de 93 jours, limit hors bornes, cursor modifié ou réutilisé avec d'autres filtres, valeur d'énumération inconnue.

Que faire. Corrigez la requête à l'aide du champ detail, qui nomme le paramètre en cause. Ne réessayez pas à l'identique.

401unauthorizedAuthentification requise

Cause. L'en-tête Authorization: Bearer <token> est absent, ou le token est inconnu, expiré ou révoqué.

Que faire. Demandez un nouveau token puis rejouez l'appel une fois. Si le nouveau token est lui aussi refusé, l'accès a été révoqué par l'enseigne.

403insufficient_scopeScope insuffisant

Cause. Votre accès n'inclut pas le scope requis par cet endpoint (indiqué dans detail).

Que faire. Demandez à l'administrateur de l'enseigne d'ajouter le scope à votre accès. Les tokens existants en bénéficient immédiatement.

403forbiddenAccès refusé

Cause. L'accès est restreint à une liste d'adresses IP et la vôtre n'en fait pas partie.

Que faire. Appelez l'API depuis une adresse autorisée, ou demandez à l'enseigne d'ajouter votre adresse.

403subscription_inactiveAbonnement inactif

Cause. L'API n'est disponible que si au moins un restaurant de l'enseigne a un abonnement O-Ven actif. Ce n'est plus le cas.

Que faire. Contactez l'enseigne. L'accès redevient disponible dès que l'abonnement est réactivé.

404not_foundRessource introuvable

Cause. L'endpoint n'existe pas, ou l'objet demandé n'existe pas ou n'appartient pas à votre périmètre (restaurant, commande, salarié d'un autre restaurant…). Les deux cas sont volontairement indiscernables.

Que faire. Vérifiez l'URL et l'identifiant. Pour un restaurant, comparez avec GET /me (restaurant_ids).

429rate_limitedTrop de requêtes

Cause. Vous avez dépassé le nombre de requêtes autorisées par minute pour votre accès.

Que faire. Attendez le nombre de secondes indiqué par l'en-tête Retry-After avant de réessayer. Voir la page Limites.

500internal_errorErreur interne

Cause. Une erreur inattendue s'est produite de notre côté.

Que faire. Réessayez plus tard avec un délai croissant. Si l'erreur persiste, transmettez-nous le request_id.