Gestion des erreurs et codes d'état HTTP

HTTP/1.1 401 Unauthorized
X-XoPort-Deny-Reason: deny_token_required
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "api_version": "2.122.13",
  "error": {
    "code": "UNAUTHORIZED",
    "reason": "deny_token_required",
    "message": "Authentication required. JSON/REST routes always require an OAuth2 token and check its scopes; the XML_PORT_IP_FILTER whitelist does not authorize them (changed in API 2.119.0). Obtain a token via POST /oauth/token (client_credentials grant)."
  }
}

Les erreurs liées aux paramètres de requête comportent en outre les champs details[], param et message pour chaque erreur (exemple sur la page API d'exportation). Utilisez error.code comme valeur, et non le texte du message.

Depuis la version v2.119.0, en cas d'appel rejeté, l'API indique le motif dans le champ reason; pour le code 401, elle l'indique également dans l'en-tête X-XoPort-Deny-Reason: par exemple deny_token_required (401, appel sans jeton) ou deny_ip_not_listed (403, adresse non présente dans XOPORT_REST_IP_LIST; uniquement dans le corps).

Le point de terminaison des jetons POST /oauth/token répond au format OAuth2 (error, error_description), et non avec ces codes : voir « Erreur au niveau du point de terminaison des jetons » ci-dessous.

Une modification de la portée sur le client ne prend effet qu’avec le prochain jeton : un jeton déjà émis conserve les portées qui lui étaient attribuées lors de son émission jusqu’à son expiration, c’est-à-dire pendant une heure maximum. Pour révoquer immédiatement l’accès dans le backend, utilisez « Révoquer les jetons » dans le menu d’actions du client (à partir de la version 4.9.168 de la boutique) ; dans les versions antérieures, désactivez puis réactivez le client ; le secret reste inchangé. En revanche, une modification de la limite de requêtes prend effet immédiatement.

Le journal d’utilisation du client ne mentionne pas les interruptions de l’exportation avec un code HTTP 400 avant le début d’une requête (erreurs de filtrage, de navigation et de chemin d’accès), ni la réponse 429. Si vous recherchez une erreur à cet endroit, vous ne trouverez donc pas ces cas ; les codes 400 sont néanmoins pris en compte dans la limite de requêtes.

Depuis la v2.122.11, Retry-After indique le nombre de secondes avant qu’une nouvelle requête ne soit acceptée (de 1 à 3 600), et le corps de la requête contient le même nombre que error.retry_after. À cela s’ajoutent les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset, que chaque réponse envoyée à un client soumis à une limite de requêtes contient (voir Clients OAuth2).

HTTP/1.1 429 Too Many Requests
Retry-After: 1260
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792327500
Content-Type: application/json; charset=utf-8

{
  "success": false,
  "api_version": "2.122.13",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit of 5000 requests per 3600 s (sliding window) exceeded.",
    "retry_after": 1260
  }
}

• La valeur déterminante pour la prochaine tentative est Retry-After. La plupart du temps, « maintenant + Retry-After» correspond exactement à X-RateLimit-Reset; si la limite d’un client vient d’être réduite, c’est Retry-After qui s’applique.
• Jusqu’à la version v2.122.10 (boutique jusqu’à la version 4.9.170), Retry-After était toujours égal à 3600, il n’y avait pas de champ retry_after et le message indiquait « Rate limit of 5000 requests/hour exceeded. ». Tenez compte de la valeur de error.code, jamais du texte du message.
• Une requête rejetée (429) ne compte pas. Il faut répartir un grand nombre de requêtes de manière uniforme sur l’heure et ralentir dès que X-RateLimit-Remaining atteint 0, au lieu d’attendre le 429.

POST /oauth/token répond, dans le format OAuth2, par error et error_description. Depuis la version v2.122.11, une portée demandée illisible (UTF-8 non valide ou une liste telle que scope[]=…) génère un code HTTP 400 invalid_scope; aucun jeton n’est émis. client_id ou client_secret sous forme de liste génèrent un code HTTP 400 invalid_request. Retry-After indique le délai d'attente (de 1 à 300 secondes) propre au point de terminaison du jeton. Toutes les erreurs liées au point de terminaison du jeton sont répertoriées sous « Clients OAuth2 ».