Virheet ja rajojen ylitykset

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 yli.

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

{
  "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ä, 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.

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.

Kirjoitustoiminto, joka luettelee Idempotency-Key-otsikon API-viitteessä, 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.