Erreurs et limites de débit

L'API de la plateforme signale les échecs avec l'enveloppe d'erreur tRPC standard. Cette page décrit sa forme, la correspondance avec les statuts HTTP, les erreurs de validation et les limites de débit propres à certaines fonctionnalités.

L'enveloppe d'erreur

Les erreurs suivent la forme d'erreur tRPC standard et, comme les réponses réussies, sont encapsulées en superjson : l'objet d'erreur se trouve sous error.json. Les champs utiles sont :

• message : un message lisible. Les messages peuvent être en français ou en anglais : ne les analysez pas, appuyez-vous sur data.code.
• data.code : un code d'erreur lisible par une machine (par ex. UNAUTHORIZED, NOT_FOUND).
• data.httpStatus : le statut HTTP correspondant, qui est aussi le statut de la réponse. Dans un lot (httpBatchLink), chaque appel garde son propre data.httpStatus ; si les appels du lot n'ont pas tous le même statut, la réponse HTTP vaut 207.
• data.path : le <router>.<procedure> qui a échoué.

{
  "error": {
    "json": {
      "message": "Please log in to access this feature. Your session may have expired.",
      "code": -32001,
      "data": {
        "code": "UNAUTHORIZED",
        "httpStatus": 401,
        "path": "auth.getSession",
        "zodError": null
      }
    }
  }
}

Code et statut HTTP

PRECONDITION_FAILED signale une action refusée dans l'état actuel de l'objet ou de la configuration (par exemple une facture déjà soldée, ou un paiement en ligne non configuré) : corrigez l'état avant de réessayer (répéter l'appel tel quel ne changera rien).

UNAUTHORIZED signifie qu'aucun identifiant valide n'a été reconnu, ou qu'aucun locataire ni site n'a pu être résolu pour l'appel. FORBIDDEN signifie que vous êtes authentifié mais qu'il vous manque la permission ou le rôle requis, que votre compte ne peut pas agir dans la portée locataire/site demandée, ou que l'abonnement du locataire n'inclut pas le module appelé. Voir Sessions et tokens.

Erreurs de validation (zodError)

Quand l'entrée échoue à la validation, l'appel échoue avec BAD_REQUEST (HTTP 400) et data.zodError décrit le problème : fieldErrors associe à chaque nom de champ une liste de messages, et formErrors liste les erreurs qui ne relèvent pas d'un champ précis. Pour toute autre erreur, zodError vaut null.

{
  "error": {
    "json": {
      "message": "…",
      "code": -32600,
      "data": {
        "code": "BAD_REQUEST",
        "httpStatus": 400,
        "path": "clients.create",
        "zodError": {
          "formErrors": [],
          "fieldErrors": {
            "email": ["Invalid email address"]
          }
        }
      }
    }
  }
}

Lisez zodError pour afficher les messages champ par champ à l'utilisateur.

Limites de débit

L'API ne publie pas de quota de requêtes général. Les fonctionnalités suivantes ont leurs propres limites :

Sur le fournisseur d'identité, une requête au-delà de la limite reçoit un HTTP 429 avec un en-tête Retry-After (en secondes). Le corps porte en général l'erreur OAuth slow_down, mais pas toujours : fiez-vous au statut et à Retry-After. Certaines procédures de l'API peuvent aussi répondre TOO_MANY_REQUESTS : patientez avant de réessayer.