# Virheet ja rajojen ylitykset
Source: https://nordvec.com/fi/docs/guides/errors-and-rate-limits

Yksi virhekuori, jonka jokainen epäonnistunut pyyntö palauttaa, rajojen ylitystiedot otsikoissa ja kuinka kirjoitus voidaan yrittää uudelleen turvallisesti.



Jokainen päätepiste epäonnistuu samalla tavalla, joten asiakas käsittelee virheet, rajoitukset ja uusintayritykset kerran ja käyttää samaa koodia kaikkialla, myös [MCP:n](/docs/guides/mcp) yli.

## Virhekuori [#virhekuori]

Jokainen ei-2xx-vastaus on yksi JSON-objekti:

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` on HTTP-tason virhe, esimerkiksi `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` tai `TOO_MANY_REQUESTS`.
* `data.reason`, kun se on olemassa, on tarkempi koneellisesti luettava syy, kuten
  `auth.key_not_found` tai `rate_limit.exceeded`. Haaraa sen perusteella eikä `message`:n perusteella,
  joka on tarkoitettu ihmisille ja voi muuttua.
* `defined` on `true`, kun toiminto luettelee kyseisen virheen
  [API-viitteessä](/docs/api), ja `false` virheille, joita mikä tahansa pyyntö voi kohdata
  (todennus, rajoitukset, tuntematon reitti).
* Validointivirhe vastaa `BAD_REQUEST`:llä, ja ongelmat ovat
  `data.formErrors`:ssä ja `data.fieldErrors`:ssä.

Jokainen vastaus sisältää myös `X-Request-ID`:n. Mainitse se, kun otat yhteyttä
tukeen, niin löydämme kyseisen pyynnön tarkasti.

## Yleiset tilakoodit [#yleiset-tilakoodit]

| Tilakoodi | Koodi                   | Toimenpide                                                            |
| --------- | ----------------------- | --------------------------------------------------------------------- |
| `400`     | `BAD_REQUEST`           | Korjaa pyyntö; `data.fieldErrors` nimeää kentät                       |
| `401`     | `UNAUTHORIZED`          | Lähetä kelvollinen avain tai istunto                                  |
| `403`     | `FORBIDDEN`             | Avaimella ei ole vaadittua käyttöoikeutta tai roolia toimintoa varten |
| `404`     | `NOT_FOUND`             | Resurssia ei ole olemassa, tai sinulla ei ole oikeutta nähdä sitä     |
| `409`     | `CONFLICT`              | Kaksoiskirjoitus on vielä kesken; yritä uudelleen pian                |
| `413`     | `PAYLOAD_TOO_LARGE`     | Pyynnön runko on yli 1 Mt; jaa massapush pienempiin eriin             |
| `429`     | `TOO_MANY_REQUESTS`     | Odota `Retry-After`, sitten yritä uudelleen                           |
| `422`     | `UNPROCESSABLE_CONTENT` | Pyyntö on hyvin muodostettu, mutta sitä ei voida soveltaa             |

## Rajoitukset [#rajoitukset]

Jokainen vastaus ilmoittaa rajoituksen, jota vastaan se laskettiin, kahdessa muodossa:

* `X-RateLimit-*`-otsikot;
* IETF:n strukturoidut kentät `RateLimit` (reaaliaikainen tila: `r` on jäljellä olevat pyynnöt,
  `t` sekuntia ikkunan nollaukseen) ja `RateLimit-Policy`
  (kiintiö: `q` on rajoitus, `w` ikkuna sekunteina).

`429` sisältää myös `Retry-After` sekunteina ja `data.retryAfterMs`. Odota vähintään niin kauan ennen seuraavaa pyyntöä;
aiempi uusintayritys lasketaan ja evätään uudelleen.

## Kirjoitusten turvallinen uusinta [#kirjoitusten-turvallinen-uusinta]

Kirjoitustoiminto, joka luettelee `Idempotency-Key`-otsikon
[API-viitteessä](/docs/api), voidaan uusia ilman, että työ tehdään kahdesti. Lähetä yksi avain loogista kirjoitusta kohden ja toista sama avain jokaisella uusintakerralla:

* sama avain samalla rungolla 24 tunnin sisällä toistaa tallennetun vastauksen;
* sama avain eri rungolla evätään `422`:llä;
* kaksoiskappale, joka saapuu, kun ensimmäinen on vielä käynnissä, saa `409`:n.

Toimintoa, jolla ei ole otsikkoa, ei ole idempotentti, joten yritä sitä uudelleen vain, kun tiedät, että ensimmäinen yritys ei onnistunut.