Virheet ja palautuminen¶
Tarkista HTTP-tila, JSON-RPC-virhe ja työkalun virhe erikseen. HTTP 200 ei yksin osoita haun onnistumista.
HTTP- ja protokollavirheet¶
| Tila | Tavallinen merkitys | Toimenpide |
|---|---|---|
| 400 | Virheellinen JSON-RPC tai tuntematon protokollaversio otsakkeessa | Korjaa pyyntö; älä yritä muuttumattomana uudelleen |
| 401 | Puuttuva, väärä, vanhentunut tai suljettu tunnus; tilin/fleetin oikeus on poistunut | Pysäytä haku ja tarkista tunnus sekä nykyiset oikeudet |
| 403 | Selaimen Origin ei ole sallittu | Käytä valtuutettua taustaohjelmaa |
| 404 | JSON-RPC-metodia ei tueta | Käytä tuettuja MCP-metodeja |
| 405 | Pyyntö ei ole POST | Käytä HTTP POST -pyyntöä |
| 413 | Pyyntörunko ylittää 65 536 tavua | Pienennä pyyntöä |
| 415 | Content-Type ei ole application/json | Lähetä JSON ja oikea otsake |
| 503 | Tunnistautumisen tietohaku ei ole käytettävissä | Yritä myöhemmin rajatulla viiveellä |
Tunnistautumisvirheen runko voi olla tyhjä. Kaikki HTTP-virheet eivät siis ole JSONia. Välityspalvelimen 429- ja 5xx-vastauksissa käytä rajattua uudelleenyritystä ja huomioi kelvollinen, enimmäisarvoon rajattu Retry-After, jos sellainen annetaan. Tässä versiossa ei luvata avainkohtaisia nopeusrajaotsakkeita tai sopimuksen mukaista kutsukapasiteettia.
Työkalutason virheet¶
Parametrivirhe, tuntematon argumentti, puuttuva tilannekuva tai lukemisen epäonnistuminen voi palautua HTTP 200 -vastauksena:
{
"jsonrpc": "2.0",
"id": 42,
"result": {
"content": [{"type": "text", "text": "Invalid snapshot cursor for this query."}],
"isError": true
}
}
Esimerkin virhe tarkoittaa, ettei tilannekuvakursori kelpaa kyseiseen hakuun. Palvelimen virhetekstit ovat englanniksi. Älä tulkitse epäonnistunutta kutsua tyhjäksi aineistoksi. Ihmisen luettavat virhetekstit eivät ole vakaita koneellisia virhekoodeja, joten älä sido pysyvää liiketoimintalogiikkaa niiden tarkkaan sanamuotoon.
Palautumissäännöt¶
- Vanhentunut tilannekuva: aloita koko rajattu haku uudelleen. Säilytä jatkosiirtojen kaksoiskäsittelyn esto, koska samoja rivejä voi tulla uudelleen.
- Liian suuri tilannekuva: jaa aikaväli pienemmäksi, tarvittaessa päiväkohtaiseksi. Älä hyväksy huomaamatta katkennutta vientiä.
- Tilannekuvakiintiö: jatka aiemmalla kursorilla tai odota vanhenemista. Uuden tilannekuvan luominen joka sivulla on virhe.
- Aikakatkaisu: toista sama kursoripyyntö rajatusti. Jos kursori ehtii vanheta, aloita uudelleen ja täsmäytä tulos.
- Virheellinen kursori: tarkista rajaukset, sivukoko, sivutustapa ja tunnuksen oikeuskonteksti. Älä muokkaa kursoria.
- Lukeminen epäonnistui: säilytä viimeisin onnistunut tila, ilmoita ylläpidolle ja yritä myöhemmin uudelleen. Älä tyhjennä vastaanottajan tietoja.
Kirjaa lokeihin oma korrelaatiotunnisteesi, työkalun nimi, tila ja yritysmäärä. Älä kirjaa Authorization-otsaketta, raakaa kalustoaineistoa tai avainta.