Virheet + nopeusrajat

Yksi virhekuori jokaisessa päätepisteessä. Standardit HTTP-statuskoodit + jäsennelty code-merkkijono ohjelmalliseen täsmäytykseen. Nopeusrajaotsakkeet jokaisessa vastauksessa, jotta voit tahdittaa itseäsi ennen kuin osut 429:ään.

Virhekuori

{
  "detail": "Human-readable summary.",
  "code": "billing.subscription_past_due",
  "field_errors": {
    "scheduled_for": ["Must be a future ISO 8601 timestamp."]
  }
}

detail — aina läsnä, turvallinen renderöidä ihmisille (se on käännetty siellä missä lokaali on saatavilla).
code — läsnä erotettavissa oleville virhetiloille. Vakaa API-versioiden yli; täsmää tähän uudelleenyrityslogiikassa.
field_errors — läsnä vain 400-validointivirheissä. Kartta kentän nimi → viestilista.

Statuskoodimatriisi

Status	Luokka	Uudelleenyritys?	Yleiset syyt
400	Validointi	Ei	Puuttuva pakollinen kenttä, virheellinen muoto, liiketoimintasäännön rikkomus
401	Auth	Ei	Puuttuva / virheellinen / peruutettu tunniste
402	Laskutus	Ei	Tilaus erääntynyt, ilmaissuunnitelman raja täynnä
403	Käyttöoikeus	Ei	Tunnisteelta puuttuu scope, tai resurssi on eri organisaatiossa
404	Ei löydy	Ei	Resurssia ei ole olemassa, tai se ei ole näkyvissä tunnisteellesi
409	Konflikti	Joskus	Idempotency-Keyn uudelleenkäytön epäsuhta, tilakonerikkomus
422	Käsittelemätön	Ei	Semanttisesti virheellinen yhdistelmä kelvollisia kenttiä
429	Nopeusrajattu	Kyllä, perääntymisellä	Tunniste- tai organisaatiokohtainen throttle täynnä
500	Palvelinvirhe	Kyllä, perääntymisellä	Odottamaton — avaa tiketti jos jatkuvaa
502 / 503 / 504	Ohimenevä	Kyllä, perääntymisellä	Ylävirta / julkaisu / kuorma

Merkittävät virhekoodit

Koodi	Status	Mitä se tarkoittaa
`billing.subscription_past_due`	402	Organisaation Stripe-tilaus on erääntynyt. Ohjaa ylläpitäjä kohtaan `/admin/billing`.
`billing.free_plan_minutes_exhausted`	402	Free-/Pilot-taso on käyttänyt 5 tarkastustaan.
`billing.signature_pack_exhausted`	402	Allekirjoituspaketin krediitit käytetty; maksa per allekirjoitus tai osta toinen paketti.
`permission_denied`	403	Tunnisteelta puuttuu scope. Katso `field_errors.required_scope`.
`idempotency.key_mismatch`	409	Sama avain, eri runko. Käytä tuoretta avainta.
`session.already_ended`	409	`end`:in kutsuminen ei-avoimessa istunnossa (yleensä turvallista — `end` on idempotentti, tämä on reunatapauksia varten).
`kyb.not_verified`	403	QES-allekirjoitus pyydetty organisaatiolle, joka ei ole läpäissyt KYB:tä.
`rate_limited`	429	Tunnistekohtainen (60 rpm) tai organisaatiokohtainen (600 rpm) throttle täynnä.

Nopeusrajaotsakkeet

Jokainen vastaus — onnistuminen tai virhe — kantaa throttle-tilan:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1716461235

X-RateLimit-Limit — tähän pyyntöön sovellettava katto.
X-RateLimit-Remaining — montako kutsua on jäljellä nykyisessä ikkunassa.
X-RateLimit-Reset — Unix-aikaleima, jolloin Remaining nollautuu.

429:ssä asetetaan myös Retry-After (sekunneissa) RFC 6585:n mukaan.

Throttle-scopet

Scope	Raja	Ikkuna
Per tunniste	60	1 minuutti
Per organisaatio (kaikkien tunnisteiden yli)	600	1 minuutti

Purskeellinen minuutin ensimmäisen sekunnin ajan. Osu kattoon, ja lisäpyynnöt ikkunan sisällä saavat 429:n.

Uudelleenyritysstrategia

Eksponentiaalinen perääntyminen jitterillä 429- / 5xx-virheille; älä yritä uudelleen 4xx-virheitä (paitsi 408, 425, 429):

async function withRetry<T>(fn: () => Promise<T>, max = 5): Promise<T> {
  let lastErr: unknown;
  for (let i = 0; i < max; i++) {
    try {
      return await fn();
    } catch (err: any) {
      const status = err?.status;
      if (status >= 400 && status < 500 && ![408, 425, 429].includes(status)) {
        throw err; // not retryable
      }
      const base = status === 429 ? (err.retryAfterMs ?? 1000) : 250 * 2 ** i;
      const jitter = Math.random() * base * 0.2;
      await new Promise((r) => setTimeout(r, base + jitter));
      lastErr = err;
    }
  }
  throw lastErr;
}

SDK:t toteuttavat tämän sisäisesti 429:llä + 5xx:llä; jos haluat mieluummin käsitellä uudelleenyritykset itse, aseta retries: 0 SDK-asetuksissa.

Virhekorrelaatio

Jokainen vastaus kantaa X-Request-Id-otsakkeen (UUID). Mainitse tämä tukitiketissä — voimme vetää täyden pyyntöjäljen pelkästä tuosta id:stä.

Mitä seuraavaksi

Tunnistautuminen — tunnisteen kierrätys jos näet 401:iä
Sivutus + idempotenssi — kuviot, jotka vuorovaikuttavat uudelleenyritysten kanssa