Erreurs

Toute erreur rendue par l'API Transaction Intelligence a la même forme : un corps application/problem+json (RFC 9457) dont le champ type identifie l'erreur de façon stable. Le catalogue complet, généré depuis le contrat, est en bas de cette page.

La forme d'une erreur

Une erreur est un objet Problem.

Un exemple, pour une date sans décalage horaire :

{
  "type": "https://noryo.app/problems/transactions/invalid_input",
  "title": "Une contrainte du schema d'entree n'est pas respectee.",
  "status": 422,
  "detail": "Le schema est ferme : un champ inconnu est refuse plutot qu'ignore.",
  "errors": [
    { "field": "occurred_at", "code": "must_be_rfc3339_with_offset" }
  ],
  "request_id": "req_01J9…"
}

Lire une réponse

Testez d'abord le Content-Type, puis le type. Un statut seul ne suffit pas : deux réponses décrites plus bas viennent de l'hébergeur, sans corps Problem.

const transaction = {
  descriptor: "CARTE 09/09 MONOPRIX PARIS 15",
  direction: "outgoing",
  occurred_at: "2026-09-09T07:31:00+02:00",
  amount: { value: "49.90", currency: "EUR" },
  payment: { rail: "card" },
  external_transaction_id: "tx-2026-09-09-0042",
};

const response = await fetch("https://api.noryo.app/transactions/v1/enrichments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "tx-2026-09-09-0042",
  },
  body: JSON.stringify(transaction),
});

const contentType = response.headers.get("content-type") ?? "";
if (contentType.startsWith("application/problem+json")) {
  const problem = await response.json();
  const code = problem.type.replace("https://noryo.app/problems/transactions/", "");
  switch (code) {
    case "rate_limited": {
      const seconds = Number(response.headers.get("retry-after"));
      // attendre `seconds`, puis rejouer la même requête, même Idempotency-Key
      break;
    }
    case "invalid_input":
    case "unknown_currency":
      // problem.errors[].field et problem.errors[].code : corriger avant de renvoyer
      break;
    case "idempotency_conflict":
      // même clé, requête différente : ne pas rejouer tel quel
      break;
    default:
      console.error(code, problem.request_id);
  }
}

Branchez-vous sur type (ou sur son dernier segment) et sur errors[].code, jamais sur title ni detail, qui sont des phrases.

Que faire, statut par statut

422 : corriger avant de renvoyer

Le champ en cause est dans errors[].field, la règle dans errors[].code. Corrigez, puis renvoyez ; une autre règle peut alors être signalée. Rejouer la même requête sans la changer rend le même 422.

Une devise hors de l'enum Money.currency est rendue sous le type unknown_currency ; toute autre contrainte sous invalid_input. La liste des codes possibles est celle du runtime, par construction : lisez la réponse 422 de chaque POST dans la référence, et les cas fréquents dans Enrichir une transaction et Couverture d'observation.

409 : même clé, autre requête

« Différente » se juge sur l'empreinte économique (fingerprint) de la transaction : deux corps qui ne diffèrent que par external_transaction_id, account_hint ou counterparty_hint ont la même empreinte et sont la même requête, rejouée en 200. Un 409 ne se rejoue donc pas tel quel : soit vous vouliez rejouer la requête d'origine, et il faut lui rendre son corps ; soit c'est une nouvelle transaction, et il lui faut une nouvelle clé. Une clé est retenue au moins 24 heures.

429 : attendre Retry-After

Le detail dit si la limite atteinte est celle de la clé ou celle du workspace. Rien n'a été calculé, rien n'a été enregistré, aucun événement n'a été émis. L'en-tête Retry-After donne, en secondes entières, le délai après lequel la requête peut passer ; rejouez alors la même requête, avec la même Idempotency-Key s'il y en avait une. Voir Limites de débit.

Ce qui compte dans le débit et l'usage

Les portes s'enchaînent dans un ordre fixe : hôte, Content-Type, taille du corps, credential, authentification et débit, JSON, Idempotency-Key, schéma, traitement. Un refus avant la credential (400 sur l'hôte, 415, 413) ou par elle (401, 403) ne touche ni vos limites de débit ni votre usage. Une fois la credential acceptée, un 400 sur le JSON ou sur l'Idempotency-Key, un 422, un 404 ou un 409 a consommé un jeton de débit et compte dans votre usage comme une requête. Les réponses 422, 404 et 409 portent les en-têtes noryo-ratelimit-limit et noryo-ratelimit-remaining, comme les succès. Voir Usage et clés d'API.

Deux réponses sans Problem

Deux réponses viennent de l'hébergeur, avant l'API, et ne sont pas des Problem : un verbe non déclaré sur un chemin déclaré rend 405 avec un corps vide et sans en-tête Allow ; un chemin inconnu rend 404. Ni l'une ni l'autre ne porte request_id. D'où le test du Content-Type avant de lire le corps : un 404 sans application/problem+json est une faute de chemin, pas un enrichissement introuvable.

Citer le request_id au support

Toute erreur rendue par l'API porte request_id dans son corps ; les succès le portent dans l'en-tête noryo-request-id. Conservez-le dans vos journaux, à côté de l'identifiant public de la clé (key_id), et donnez-le au support. Ne joignez jamais le secret de la clé.

Le catalogue

Le catalogue ci-dessous est généré depuis le contrat servi sur https://api.noryo.app/openapi.json : la liste des type est celle que le runtime peut produire. Chaque code a sa page sous /transaction-intelligence/errors/<code>, par exemple /transaction-intelligence/errors/rate_limited.

Toutes les erreurs