Vead ja taastumine

Kasuta püsivaid veakoode, et otsustada, kas parandada, oodata või uuesti proovida.

Mida teha

Tee otsused HTTP-oleku ja error.code, mitte inimloetava error.message põhjal.
401 nõuab kehtivat autentimist; 403 juurdepääsu või paketi muudatust; 409 vastuolulise toimingu või ressursiversiooni kontrollimist.

Juurdepääs keelatud ja korduskatsed

401: 401 ei tähenda alati tokeni aegumist. Kui token on aegunud, hangi uus ja korda lugemist kõige rohkem üks kord. Kui tokeni hankimine tagastab 401, kontrolli võtit ja lõpeta automaatsed katsed.
403: 403 korral kontrolli õigusi, IP-piiranguid ja paketti. Uus token ei taasta tühistatud juurdepääsu.

Autentimine

Korduskatsete reeglid

Ajutiste tõrgete korral piira korduskatsete arvu ning suurenda ooteaega koos juhusliku nihkega.
Järgi päist Retry-After, kui see on olemas.
Muudatuse ajalõpu korral võib tulemus olla teadmata: sama loogilise toimingu kordamisel säilita sama Idempotency-Key ja muutmata päring.
Allolev kataloog selgitab kõiki avaldatud veakoode.

Turvalised muudatused

Päringusageduse piirangud

422 / 409

Hindade puhul annab vigane valuutavorming või summa täpsus veateate 422 request.validation_failed.
Kehtiv valuutakood, mis ei vasta valitud hinnakirjale, annab veateate 409 resource.version_conflict.
Enne uuesti proovimist kontrolli konteksti ja versioone.

Veakataloog

400request.malformedPäringut ei saa parsida.

Mida teha: Kontrolli JSON-i süntaksit, URL-kodeeringut ja päringu struktuuri.
Korduskatsete reeglid: Proovi pärast päringu parandamist uuesti.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI-võti või pääsutoken on vigane, aegunud või tühistatud.

Mida teha: Kontrolli poe URL-i ja pääsuandmeid. Hangi aktiivse API-võtmega uus token.
Korduskatsete reeglid: Proovi pärast autentimise parandamist uuesti; väldi korduvaid päringuid vigase tokeniga.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredNõutav Authorization-päis puudub või selle skeem on vale.

Mida teha: Tokeni taotlemisel kasuta ApiKey ning ressursitoimingutel Bearer skeemi.
Korduskatsete reeglid: Proovi pärast õige päise lisamist uuesti.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedTeenus ei suutnud määrata usaldusväärset kliendi IP-aadressi.

Mida teha: Palu poe operaatoril kontrollida siseneva liikluse teed. Ära lisa ise edastuspäiseid.
Korduskatsete reeglid: Proovi pärast usaldusväärse ühendustee taastamist uuesti.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedLähte-IP-aadress ei kuulu võtme lubatud aadresside nimekirja.

Mida teha: Kasuta heakskiidetud lähteaadressi või palu volitatud administraatoril muuta võtme IP-nimekirja.
Korduskatsete reeglid: Proovi uuesti alles pärast aadressi lubamist.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedVõtmel puudub selle toimingu nõutav kehtiv õigus.

Mida teha: Kontrolli toimingu nõutavaid ja tingimuslikke õigusi, võtmele antud õigusi ning võtme väljastaja juurdepääsu.
Korduskatsete reeglid: Proovi pärast seda, kui volitatud administraator annab vajaliku juurdepääsu.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledSelle poe API-juurdepääs on keelatud.

Mida teha: Palu poe omanikul kontrollida aktiivset paketti ja API saadavust.
Korduskatsete reeglid: Ära korda päringut enne API-juurdepääsu lubamist.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededMuudatus ületaks praeguse paketi piirangu.

Mida teha: Kontrolli kehtivat ressursipiirangut ning kohanda kavandatud muudatust või paketti.
Korduskatsete reeglid: Proovi pärast piirangu lahendamist uuesti; päringu muutumisel kasuta uut idempotentsusvõtit.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledPraegune pakett ei sisalda seda toimingut.

Mida teha: Kontrolli toimingu juures näidatud minimaalset paketti.
Korduskatsete reeglid: Proovi uuesti, kui pakett lubab toimingut ja võtmel on nõutavad õigused.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedPaketi piirang blokeerib selle ressursi.

Mida teha: Palu omanikul lahendada ressursile kehtiv paketipiirang.
Korduskatsete reeglid: Ära korda sama päringut, kuni ressurss on blokeeritud.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundRessurss puudub, on kustutatud või pole antud identifikaatoriga kättesaadav.

Mida teha: Kontrolli poodi, ressursi teed ja identifikaatorit. Kasuta selle poe tagastatud identifikaatoreid.
Korduskatsete reeglid: Proovi uuesti ainult pärast sihi parandamist või selle olemasolu kinnitamist.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedLõpp-punkt ei toeta seda HTTP-meetodit.

Mida teha: Kasuta dokumenteeritud meetodit; Allow-päis näitab toetatud meetodeid.
Korduskatsete reeglid: Ära korda toetamata meetodit.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedSee idempotentsusvõti kuulub teisele päringule.

Mida teha: Leia algne toiming. Kasuta uut võtit ainult teadlikult uue loogilise toimingu jaoks.
Korduskatsete reeglid: Ära korda muudetud sisu vastuolus oleva võtmega.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsKordumatu väärtus on vastuolus olemasoleva ressursiga.

Mida teha: Loe olemasolev ressurss ja otsusta, kas seda kasutada või valida teine kordumatu väärtus.
Korduskatsete reeglid: Ära korda sama vastuolulist loomist.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useTeised ressursid sõltuvad endiselt sellest ressursist.

Mida teha: Kontrolli sõltuvusi ning eemalda või muuda need toetatud toimingutega enne kustutamist.
Korduskatsete reeglid: Proovi pärast sõltuvuste lahendamist uuesti.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictPraegune äriline seisund takistab seda muudatust.

Mida teha: Loe praegune seisund ja vali kehtiv äriline üleminek.
Korduskatsete reeglid: Ära sunni vastuolulist muudatust automaatselt peale ega saada seda korduvalt.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictTeine muudatus muutis ressurssi pärast sinu loetud versiooni.

Mida teha: Loe uusim seisund, kooskõlasta oma muudatus ja saada uus expected_version.
Korduskatsete reeglid: Kasuta parandatud toimingu jaoks uut idempotentsusvõtit; ära kirjuta andmeid pimesi üle.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largePäring ületab suuruspiirangut.

Mida teha: Vähenda sisu või jaga töö toetatud üksiktoiminguteks.
Korduskatsete reeglid: Proovi väiksemaid kehtivaid toiminguid nende oma idempotentsusvõtmetega.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeMeediatüüp või sisukodeering pole toetatud.

Mida teha: JSON-muudatuste jaoks kasuta Content-Type: application/json ning toetatud tihendamata sisu.
Korduskatsete reeglid: Proovi pärast meediatüübi või kodeeringu parandamist uuesti.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedÜks või mitu välja või parameetrit ei läbi valideerimist.

Mida teha: Vaata error.fields ning kontrolli kohustuslikke välju, null-i lubamist, identifikaatoreid ja lubatud väärtusi.
Korduskatsete reeglid: Saada parandatud päring; muudetud kirjutuspäring on uus loogiline toiming.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullLühike API järjekord on täis; päringu täitmine ei ole alanud.

Mida teha: Pane päringud järjekorda ja järgi vastuse Retry-After päist.
Korduskatsete reeglid: Oota vähemalt Retry-After sekundit ja lisa juhuslik viivitus. Muudatuse kordamisel säilita algne võti ja sisu.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutAPI järjekorras ootamise aeg sai läbi; päringu täitmine ei ole alanud.

Mida teha: Pane päringud järjekorda ja järgi vastuse Retry-After päist.
Korduskatsete reeglid: Oota vähemalt Retry-After sekundit ja lisa juhuslik viivitus. Muudatuse kordamisel säilita algne võti ja sisu.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededPäringusagedus ületab kehtivat piirangut.

Mida teha: Pane päringud järjekorda ja järgi vastuse Retry-After päist.
Korduskatsete reeglid: Oota vähemalt Retry-After sekundit ja lisa juhuslik viivitus. Muudatuse kordamisel säilita algne võti ja sisu.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorIlmnes ootamatu teenuseviga.

Mida teha: Salvesta päringu identifikaator ja vea püsimisel võta ühendust operaatoriga; ära lisa logidesse pääsuandmeid.
Korduskatsete reeglid: Kasuta piiratud arvu kasvava viivitusega korduskatseid. Muudatusel säilita algne idempotentsusvõti ja muutmata sisu.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseLüüs ei saanud API-lt kehtivat vastust.

Mida teha: Säilita päringu identifikaator. Ebaõnnestunud vastus ei tõesta, et muudatust ei rakendatud.
Korduskatsete reeglid: Kasuta piiratud arvu kasvava viivitusega korduskatseid; korda sama loogilist muudatust algse Idempotency-Key ja sisuga.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI ei suuda ajutiselt päringut töödelda.

Mida teha: Järgi Retry-After päist, kui see on olemas, ja katkestuse püsimisel säilita päringu identifikaator.
Korduskatsete reeglid: Kasuta piiratud arvu kasvava ja juhusliku viivitusega korduskatseid; sama muudatuse kordamisel säilita võti ja sisu.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutLüüsi ooteaeg API vastusele lõppes.

Mida teha: Säilita päringu identifikaator ja käsitle muudatuse tulemust teadmata tulemusena.
Korduskatsete reeglid: Kasuta piiratud arvu kasvava viivitusega korduskatseid; muudatusel säilita algne idempotentsusvõti ja muutmata sisu.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}