Erreurs

Branchez sur le code d'erreur, jamais sur le message. Le tableau est généré à partir du document OpenAPI.

Erreurs

Statut	Code	Signification
400	invalid_request	Erreur de schéma. details.path indique le champ fautif.
401	unauthorized	Clé API absente ou inconnue.
402	quota_exceededRetry-After	Quota mensuel atteint. Retry-After donne le nombre de secondes avant le passage au mois suivant.
403	key_revoked	La clé existe mais ne peut pas être utilisée : elle a été révoquée, ou l'abonnement Engine API du compte n'est plus actif. Le champ message précise lequel des deux.
404	not_found	Route inexistante — c'est aussi ce que vous obtenez pour le bon chemin avec la mauvaise méthode.
409	idempotency_conflictRetry-After	Uniquement avec l'en-tête Idempotency-Key : la clé a déjà servi pour une autre requête (idempotency_conflict — utilisez une nouvelle clé), ou la première requête avec cette clé est encore en cours (idempotency_in_progress — réessayez après Retry-After pour recevoir sa réponse). Jamais facturé.
409	idempotency_in_progressRetry-After	Uniquement avec l'en-tête Idempotency-Key : la clé a déjà servi pour une autre requête (idempotency_conflict — utilisez une nouvelle clé), ou la première requête avec cette clé est encore en cours (idempotency_in_progress — réessayez après Retry-After pour recevoir sa réponse). Jamais facturé.
413	too_large	Entrée au-delà d'une limite (voir Limites).
429	busyRetry-After	Capacité momentanément saturée ou — sur tout chemin authentifié par clé — votre adresse a envoyé trop de clés API inconnues en une minute. Retry-After en secondes ; cela ne compte jamais dans votre quota.
500	internal	Erreur inattendue, ou backend d'authentification injoignable (les requêtes échouent en mode fermé).
503	service_unavailable	Un moteur demandé ne peut pas être servi actuellement — le moteur de nesting, ou le moteur max asynchrone. Pour max il y a deux causes, et le champ message précise laquelle : le palier n'est pas intégré à ce déploiement, ou il l'est mais le worker qui résout les travaux ne répond pas. Fail-closed avant qu'un appel ne soit réservé : cela ne coûte donc jamais rien.
504	solve_timeout	Le calcul a dépassé sa limite stricte de temps. Sur les chemins rectangulaires, c'est le proxy qui l'applique ; sur /v1/optimize/nest, le moteur applique son propre budget, plus court, et répond solve_timeout dans l'enveloppe habituelle. Un appel abandonné par le proxy n'est pas facturé.

Corps d'erreur

Toutes les erreurs produites par le moteur lui-même utilisent la même enveloppe. Branchez votre code sur error, qui est un code stable ; jamais sur message, dont la formulation peut changer d'une version à l'autre. details est présent sur invalid_request, où path nomme le champ fautif, et sur too_large, où max et got donnent le plafond et ce que vous avez envoyé.

Exception : un corps de requête au-delà du plafond de taille porte maxBytes à la place. Un engine inconnu ajoute available, les ids de moteur que ce déploiement accepte.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "invalid_request",
  "message": "parts[0].h: must be greater than 0",
  "details": { "path": "parts[0].h" }
}

HTTP/1.1 402 Payment Required
Retry-After: 41400
Content-Type: application/json; charset=utf-8

{ "error": "quota_exceeded", "message": "monthly quota exhausted" }

402 et 429 portent tous deux un en-tête Retry-After en secondes. Sur 402, il décompte jusqu'à la réinitialisation du quota, à 00:00 UTC le 1er du mois suivant ; sur 429, il s'agit d'un court délai d'attente, et un 429 ne consomme jamais de quota — l'appel réservé est restitué.
Les refus de la clé de démonstration publique utilisent la même enveloppe : hors de son périmètre (nesting, le moteur max, usage, jobs, import, un travail au-delà de ses limites de taille) un 403 key_revoked avec details.reason "demo_scope" ; à sa limite de débit un 429 busy avec details.reason "demo_rate_limit" et details.limit.
Les deux portent details.testKeyUrl, où l'on crée une clé de test gratuite, et chaque réponse de démonstration porte l'en-tête X-CutOptim-Demo: true.
Un échec de routage répond not_found, un code délibérément absent de la liste ci-dessus parce qu'il est produit par le routeur et non par le contrat de l'API. Vous obtenez 404 et non 405 lorsque le chemin est bon mais la méthode mauvaise : les quatre endpoints d'optimisation sont uniquement en POST.
Sur les chemins rectangulaires, le 504 provient du reverse proxy et non du moteur : son corps est donc celui du proxy et non cette enveloppe JSON ; un seul travail dans les limites d'entrée ci-dessous reste bien en deçà, mais plusieurs des travaux les plus lourds arrivés ensemble peuvent le dépasser en file d'attente — et un appel abandonné par le proxy n'est pas facturé. /v1/optimize/nest fait exception : ce calcul est un sous-processus doté de son propre budget, délibérément maintenu sous la limite du proxy — un dépassement y utilise donc cette enveloppe, avec le code solve_timeout.

Un moteur est en panne ? La page d’état montre en direct l’état du site, de l’Engine API, du moteur de nesting et du moteur asynchrone max : État du service ↗