Rate limits

The Transaction Intelligence API protects its engine from bursts with an operational rate limit, published in the contract under the x-noryo-rate-limit extension of openapi.json, with a policy version (policy_version: debit_ti_v1).

What it is, and what it is not

The contract describes it as operational burst protection (kind: operational_burst_protection) and states explicitly what it is not:

Two token buckets

The algorithm is a token bucket (token_bucket), applied to two scopes at once:

• the key: every API key has its own bucket;
• the workspace: a second bucket bounds the sum of all the workspace's keys: a hundred keys do not make a hundred times the limit.

The values in force are the contract's:

Each bucket has a capacity (the tolerated burst) and a refill rate (the sustainable pace, in tokens per second). "N requests per minute" translates that pair: a key at rest can empty its bucket in one go, then carries on at the refill rate.

The count is central and atomic, one request at a time, with no per-server local counter. The environment is part of the bucket's identity (environment_scoped): the published values are the sandbox's. Production is not open, and its settings are not a commitment. See Sandbox limitations.

Reading the headers

As soon as a request is authenticated, the response carries the state of the limit, refusals included.

noryo-ratelimit-remaining can read zero while your key still has tokens: the workspace bucket is then the empty one.

When the limit is reached: 429

Beyond the limit, the API answers 429 with an application/problem+json body of type rate_limited and a Retry-After header. Nothing was computed, nothing was stored, no event was emitted. The request can be replayed as is once the delay has passed.

{
  "type": "https://noryo.app/problems/transactions/rate_limited",
  "title": "Trop de requetes.",
  "status": 429,
  "detail": "La limite de debit de cette clef est atteinte. Rejouez apres le delai de Retry-After.",
  "request_id": "req_01J9…"
}

When the workspace is the scope that refused, the detail says so. title and detail are texts meant for a person, written in French by the API: base your logic on type and status, never on their wording. See the error catalogue and the Errors page.

What consumes a token, and what does not

The contract fixes the processing order: host, content type, body size, credential, then authentication, prefix, usage and rate limit in a single transaction, then JSON, Idempotency-Key, schema and business logic. The token is consumed as soon as authentication succeeds, before the body is read at all: every authenticated request consumes one, whatever its response.

The three counted operations are POST /transactions/v1/enrichments, GET /transactions/v1/enrichments/{enrichment_id} and POST /transactions/v1/coverage-windows, one token each: a read costs as much as an enrichment.

Retrying properly

1. Honour Retry-After. Wait at least the delay given: it is the number of seconds before the bucket that refused will cover a new request.
2. Replay the same request, with the same Idempotency-Key. A 429 is decided before the body is read: the replayed request is processed as if for the first time. If an earlier attempt did succeed but the response never reached you, the same key gets you a 200 replay rather than a duplicate. See Enrich a transaction.
3. Cap your attempts and smooth your sending. When 429s repeat, send at the refill rate rather than adding attempts: the capacity absorbs an occasional peak, it is not a sustainable rate.
4. Watch noryo-ratelimit-remaining and slow down as it approaches zero.
5. Coordinate your keys. Spreading load across several keys adds no capacity beyond the workspace bucket.

A fetch example that honours Retry-After and keeps the Idempotency-Key from one attempt to the next:

async function enrich(transaction: unknown, idempotencyKey: string, maxAttempts = 3) {
  for (let attempt = 1; ; attempt++) {
    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": idempotencyKey,
      },
      body: JSON.stringify(transaction),
    });

    if (response.status !== 429 || attempt >= maxAttempts) return response;

    // Retry-After is in whole seconds.
    const seconds = Number(response.headers.get("retry-after") ?? "1");
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

const response = await enrich(
  {
    descriptor: "PRLV SEPA NETFLIX INTERNATIONAL",
    direction: "outgoing",
    occurred_at: "2026-09-05T03:10:00+02:00",
    amount: { value: "13.49", currency: "EUR" },
    payment: { rail: "sepa_direct_debit" },
  },
  crypto.randomUUID(),
);
console.log(response.status, response.headers.get("noryo-ratelimit-remaining"));

Where to see your 429s

429s appear on Platform, on the Usage page, Transaction Intelligence section, in the category of limited requests, per key and per workspace. 401s never appear there: a revoked or unknown key is not counted. See Usage and API keys.