Errors

Every error returned by the Transaction Intelligence API has the same shape: an application/problem+json body (RFC 9457) whose type field identifies the error in a stable way. The full catalogue, generated from the contract, is at the bottom of this page.

The shape of an error

An error is a Problem object.

An example, for a timestamp without a UTC offset:

{
  "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…"
}

Reading a response

Check the Content-Type first, then the type. A status on its own is not enough: two responses described further down come from the host, without a Problem body.

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"));
      // wait `seconds`, then replay the same request with the same Idempotency-Key
      break;
    }
    case "invalid_input":
    case "unknown_currency":
      // problem.errors[].field and problem.errors[].code: fix before resending
      break;
    case "idempotency_conflict":
      // same key, different request: do not replay as is
      break;
    default:
      console.error(code, problem.request_id);
  }
}

Branch on type (or on its last segment) and on errors[].code, never on title or detail, which are sentences.

What to do, status by status

422: fix before resending

The offending field is in errors[].field, the rule in errors[].code. Fix it, then resend; another rule may then be reported. Replaying the same request unchanged returns the same 422.

A currency outside the Money.currency enum is returned under the unknown_currency type; every other constraint under invalid_input. The list of possible codes is the runtime's own, by construction: read the 422 response of each POST in the reference, and the common cases in Enrich a transaction and Observation coverage.

409: same key, different request

"Different" is judged on the economic fingerprint (fingerprint) of the transaction: two bodies that differ only by external_transaction_id, account_hint or counterparty_hint share the same fingerprint and are the same request, replayed as 200. A 409 therefore cannot be replayed as is: either you meant to replay the original request, and it needs its original body back; or this is a new transaction, and it needs a new key. A key is retained for at least 24 hours.

429: wait for Retry-After

The detail says whether the limit reached is the key's or the workspace's. Nothing was computed, nothing was stored, no event was emitted. The Retry-After header gives, in whole seconds, the delay after which the request can go through; then replay the same request, with the same Idempotency-Key if there was one. See Rate limits.

What counts towards rate limits and usage

The gates run in a fixed order: host, Content-Type, body size, credential, authentication and rate limiting, JSON, Idempotency-Key, schema, processing. A refusal before the credential (400 on the host, 415, 413) or by it (401, 403) touches neither your rate limits nor your usage. Once the credential is accepted, a 400 on the JSON or on the Idempotency-Key, a 422, a 404 or a 409 has consumed a rate-limit token and counts towards your usage as a request. The 422, 404 and 409 responses carry the noryo-ratelimit-limit and noryo-ratelimit-remaining headers, as successes do. See Usage and API keys.

Two responses without a Problem

Two responses come from the host, before the API, and are not Problem objects: an undeclared verb on a declared path returns 405 with an empty body and no Allow header; an unknown path returns 404. Neither carries a request_id. Hence the Content-Type check before reading the body: a 404 without application/problem+json is a wrong path, not a missing enrichment.

Quoting the request_id to support

Every error returned by the API carries request_id in its body; successes carry it in the noryo-request-id header. Keep it in your logs, next to the key's public identifier (key_id), and give it to support. Never include the key's secret.

The catalogue

The catalogue below is generated from the contract served at https://api.noryo.app/openapi.json: the list of type values is the one the runtime can produce. Each code has its own page under /transaction-intelligence/errors/<code>, for example /transaction-intelligence/errors/rate_limited.

All errors