flexway
FRENParler à un expert

Erreurs

RéférenceDéveloppeursDepuis la version 0.1.0

Markdown

Sur cette page

Un refus porte toujours un code stable sur lequel aiguiller. Le même code traverse REST, gRPC, MCP et les canaux asynchrones.

Côté produit : Passerelle d'API ; côté exploitation : Dépannage.

Le format

{
  "type": "https://flexway.dev/problems/upstream_timeout",
  "title": "The upstream did not answer within its budget",
  "status": 504,
  "detail": "Operation getOrder exceeded its 2s budget.",
  "instance": "/orders/42",
  "code": "upstream_timeout",
  "request_id": "01J9Z2K7QWE",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Aiguillez sur code (ou sur type, que l'exploitant peut rediriger vers son portail), jamais sur title ou detail. Une erreur ne contient jamais le message interne de l'API, un nom d'hôte ni une donnée personnelle.

Les codes

Statut code À qui d'agir
400 malformed_request Vous : requête illisible ou paramètre non déclaré
401 unauthenticated Vous : identifiant absent ou invalide
403 forbidden Vous : portée, rôle ou tenant insuffisant
404 not_found Vous : route non déclarée
405 method_not_allowed Vous : voir Allow
412 precondition_failed Vous : If-Match non satisfait, ou reprise SSE hors historique
413 payload_too_large Vous
415 unsupported_media_type Vous : voir Accept
422 invalid_request Vous : voir errors
428 idempotency_key_required Vous : ajouter Idempotency-Key
429 rate_limited Vous : ralentir, voir Retry-After
429 quota_exceeded Vous : quota du jour ou du mois dépensé
500 internal_error La passerelle
502 upstream_error L'API
502 response_too_large L'API
503 upstream_unavailable L'API : réessayer après Retry-After
503 overloaded La plateforme : réessayer après Retry-After
504 upstream_timeout L'API : issue inconnue pour une écriture
selon l'API upstream_status L'API : erreur d'un amont gRPC, ou statut traduit par l'exploitant

400 dit « je n'ai pas pu lire », 422 « j'ai lu, et c'est faux » ; 429 est votre débit, 503 notre capacité ; 502 une réponse inexploitable, 504 pas de réponse à temps.

Sur les autres surfaces

Surface Représentation
/v1/* (inférence) Enveloppe OpenAI : unauthenticated -> authentication_error, forbidden -> permission_error, rate_limited -> rate_limit_error, invalid_request -> invalid_request_error ; le code de la passerelle est gardé (inférence)
gRPC google.rpc.Status, ErrorInfo.reason = le code (gRPC)
MCP Résultat isError portant le problème (MCP)
SSE, WebSocket event: error ou dernier message, puis fermeture (canaux asynchrones)

Étapes suivantes