Napake in obnovitev

S stabilnimi kodami napak določite, ali zahtevo popraviti, počakati ali poskusiti znova.

Kaj storiti

Odločajte se na podlagi statusa HTTP in error.code, ne besedila error.message.
Status 401 zahteva veljavno preverjanje pristnosti; 403 spremembo dostopa ali paketa; 409 preverjanje nasprotujoče si operacije ali različice vira.

Zavrnjen dostop in ponovni poskusi

401: 401 ne pomeni vedno, da je žeton potekel. Če je potekel, pridobite novega in branje ponovite največ enkrat. Če pridobivanje žetona vrne 401, preverite ključ in ustavite samodejne poskuse.
403: Pri 403 preverite dovoljenja, omejitve IP in paket. Nov žeton ne povrne preklicanega dostopa.

Preverjanje pristnosti

Pravila ponavljanja

Pri začasnih napakah uporabite omejeno število ponovitev z naraščajočim in naključnim zamikom.
Upoštevajte Retry-After, kadar je naveden.
Ob časovni prekoračitvi zapisa je izid lahko neznan: pri ponovitvi iste logične operacije ohranite isti Idempotency-Key in nespremenjeno zahtevo.
Spodnji katalog pojasnjuje vse objavljene kode napak.

Varni zapisi

Omejitve pogostosti zahtev

422 / 409

Pri cenah neveljavna oblika valute ali natančnost zneska vrne 422 request.validation_failed.
Veljavna koda valute, ki se ne ujema z izbranim cenikom, vrne 409 resource.version_conflict.
Pred ponovnim poskusom preverite kontekst in različice.

Katalog napak

400request.malformedZahteve ni mogoče razčleniti.

Kaj storiti: Preverite skladnjo JSON, kodiranje URL in strukturo zahteve.
Pravila ponavljanja: Poskusite znova po popravku zahteve.

JSON

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

401authentication.invalid_credentialsKljuč API ali dostopni žeton je neveljaven, potekel ali preklican.

Kaj storiti: Preverite URL trgovine in poverilnico. Z aktivnim ključem API pridobite nov žeton.
Pravila ponavljanja: Poskusite znova po popravku preverjanja pristnosti; ne ponavljajte neveljavnih zahtev za žeton.

JSON

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

401authentication.requiredManjka zahtevana glava Authorization ali je njena shema napačna.

Kaj storiti: Za pridobitev žetona uporabite ApiKey, za operacije virov pa Bearer.
Pravila ponavljanja: Poskusite znova po dodajanju pravilne glave.

JSON

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

403authorization.client_ip_unverifiedStoritev ni mogla zanesljivo določiti naslov IP odjemalca.

Kaj storiti: Upravljavca trgovine prosite, naj preveri vhodno povezavo. Posredniških glav ne dodajajte sami.
Pravila ponavljanja: Poskusite znova po obnovitvi zaupanja vredne povezave.

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_allowedIzvorni naslov IP ni na seznamu dovoljenih naslovov ključa.

Kaj storiti: Uporabite odobren izvorni naslov ali prosite pooblaščenega skrbnika za ureditev seznama IP ključa.
Pravila ponavljanja: Poskusite znova šele, ko je naslov dovoljen.

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_deniedKljuč nima veljavnega dovoljenja, potrebnega za to operacijo.

Kaj storiti: Preverite obvezna in pogojna dovoljenja operacije, dodelitve ključu in dostop osebe, ki ga je izdala.
Pravila ponavljanja: Poskusite znova, ko pooblaščeni skrbnik dodeli zahtevani dostop.

JSON

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

403entitlements.api_disabledDostop API je za to trgovino onemogočen.

Kaj storiti: Lastnika trgovine prosite, naj preveri aktivni paket in dostopnost API.
Pravila ponavljanja: Ne ponavljajte zahteve, dokler dostop API ni omogočen.

JSON

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

403entitlements.limit_exceededSprememba bi presegla omejitev trenutnega paketa.

Kaj storiti: Preverite veljavno omejitev vira in prilagodite načrtovano spremembo ali paket.
Pravila ponavljanja: Poskusite znova po odpravi omejitve; če se zahteva spremeni, uporabite nov ključ idempotentnosti.

JSON

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

403entitlements.operation_disabledTrenutni paket ne vključuje te operacije.

Kaj storiti: Preverite najnižji paket, naveden pri operaciji.
Pravila ponavljanja: Poskusite znova, ko paket dovoljuje operacijo in ima ključ potrebna dovoljenja.

JSON

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

403entitlements.resource_blockedTa vir je blokiran zaradi omejitve paketa.

Kaj storiti: Lastnika prosite, naj odpravi omejitev paketa za ta vir.
Pravila ponavljanja: Iste zahteve ne ponavljajte, dokler vir ostaja blokiran.

JSON

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

404resource.not_foundVir ne obstaja, je izbrisan ali ni na voljo pod navedenim identifikatorjem.

Kaj storiti: Preverite trgovino, pot vira in identifikator. Uporabite identifikatorje, ki jih vrne ta trgovina.
Pravila ponavljanja: Poskusite znova šele po popravku cilja ali potrditvi njegovega obstoja.

JSON

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

405request.method_not_allowedKončna točka ne podpira te metode HTTP.

Kaj storiti: Uporabite dokumentirano metodo; glava Allow navaja podprte metode.
Pravila ponavljanja: Ne ponavljajte nepodprte metode.

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_reusedTa ključ idempotentnosti pripada drugi zahtevi.

Kaj storiti: Poiščite izvirno operacijo. Nov ključ uporabite samo za namerno novo logično operacijo.
Pravila ponavljanja: Ne ponavljajte spremenjenih podatkov z nasprotujočim ključem.

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_existsEnolična vrednost je v sporu z obstoječim virom.

Kaj storiti: Preberite obstoječi vir in se odločite, ali ga uporabiti ali izbrati drugo enolično vrednost.
Pravila ponavljanja: Ne ponavljajte istega nasprotujočega ustvarjanja.

JSON

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

409resource.in_useDrugi viri so še odvisni od tega vira.

Kaj storiti: Preglejte odvisnosti in jih pred brisanjem odstranite ali spremenite s podprtimi operacijami.
Pravila ponavljanja: Poskusite znova po razrešitvi odvisnosti.

JSON

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

409resource.state_conflictTrenutno poslovno stanje preprečuje to spremembo.

Kaj storiti: Preberite trenutno stanje in izberite veljaven poslovni prehod.
Pravila ponavljanja: Nasprotujoče spremembe ne vsiljujte samodejno in je ne pošiljajte znova in znova.

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_conflictDrug zapis je spremenil vir po različici, ki ste jo prebrali.

Kaj storiti: Preberite najnovejše stanje, uskladite spremembo in pošljite novi expected_version.
Pravila ponavljanja: Za popravljeno operacijo uporabite nov ključ idempotentnosti; podatkov ne prepisujte brez preverjanja.

JSON

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

413request.too_largeZahteva presega omejitev velikosti.

Kaj storiti: Zmanjšajte podatke ali delo razdelite na podprte posamezne operacije.
Pravila ponavljanja: Ponovite manjše veljavne operacije z njihovimi lastnimi ključi idempotentnosti.

JSON

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

415request.unsupported_media_typeVrsta medija ali kodiranje vsebine ni podprto.

Kaj storiti: Pri zapisih JSON uporabite Content-Type: application/json in podprto nestisnjeno telo.
Pravila ponavljanja: Poskusite znova po popravku vrste medija ali kodiranja.

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_failedEno ali več polj oziroma parametrov ni prestalo preverjanja.

Kaj storiti: Preglejte error.fields, nato preverite obvezna polja, dovoljenje za null, identifikatorje in dovoljene vrednosti.
Pravila ponavljanja: Pošljite popravljeno zahtevo; spremenjeni zapis je nova logična operacija.

JSON

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

429capacity.queue_fullKratka čakalna vrsta API-ja je polna; izvajanje zahteve se še ni začelo.

Kaj storiti: Zahteve razvrstite v čakalno vrsto in upoštevajte glavo odgovora Retry-After.
Pravila ponavljanja: Počakajte najmanj Retry-After sekund in dodajte naključni zamik. Pri ponovitvi zapisa ohranite izvirni ključ in podatke.

JSON

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

429capacity.wait_timeoutČas čakanja v čakalni vrsti API-ja je potekel; izvajanje zahteve se še ni začelo.

Kaj storiti: Zahteve razvrstite v čakalno vrsto in upoštevajte glavo odgovora Retry-After.
Pravila ponavljanja: Počakajte najmanj Retry-After sekund in dodajte naključni zamik. Pri ponovitvi zapisa ohranite izvirni ključ in podatke.

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.exceededPogostost zahtev presega veljavno omejitev.

Kaj storiti: Zahteve razvrstite v čakalno vrsto in upoštevajte glavo odgovora Retry-After.
Pravila ponavljanja: Počakajte najmanj Retry-After sekund in dodajte naključni zamik. Pri ponovitvi zapisa ohranite izvirni ključ in podatke.

JSON

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

500internal.errorPrišlo je do nepričakovane napake storitve.

Kaj storiti: Zabeležite identifikator zahteve in se ob ponavljanju napake obrnite na upravljavca; poverilnice izključite iz dnevnikov.
Pravila ponavljanja: Uporabite omejen naraščajoči zamik. Pri zapisu ohranite izvirni ključ idempotentnosti in nespremenjene podatke.

JSON

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

502gateway.bad_responsePrehod ni prejel veljavnega odgovora API.

Kaj storiti: Shranite identifikator zahteve. Neuspešen odgovor ne dokazuje, da zapis ni bil izveden.
Pravila ponavljanja: Uporabite omejen naraščajoči zamik; isti logični zapis ponovite z izvirnim Idempotency-Key in podatki.

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 začasno ne more obdelati zahteve.

Kaj storiti: Upoštevajte Retry-After, če je naveden, in shranite identifikator zahteve, če izpad traja.
Pravila ponavljanja: Uporabite omejen naraščajoči zamik z naključno komponento; pri ponovitvi istega zapisa ohranite ključ in podatke.

JSON

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

504gateway.timeoutPrehod je med čakanjem na API presegel časovno omejitev.

Kaj storiti: Shranite identifikator zahteve in izid zapisa obravnavajte kot neznan.
Pravila ponavljanja: Uporabite omejen naraščajoči zamik; pri zapisu ohranite izvirni ključ idempotentnosti in nespremenjene podatke.

JSON

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