Klaidos ir atkūrimas

Pagal stabilius klaidų kodus spręskite, ar taisyti, palaukti, ar kartoti užklausą.

Ką daryti

Programos eigą valdykite pagal HTTP būseną ir error.code, o ne žmonėms skirtą error.message.
401 reikalauja tinkamo tapatybės patvirtinimo; 403 – prieigos ar plano pakeitimo; 409 – patikrinti konfliktuojančią operaciją arba ištekliaus versiją.

Prieiga uždrausta ir pakartotiniai bandymai

401: 401 ne visada reiškia pasibaigusį žetono galiojimą. Jei jis baigėsi, gaukite naują ir kartokite skaitymą daugiausia vieną kartą. Jei žetono gavimas grąžina 401, patikrinkite raktą ir sustabdykite automatinius bandymus.
403: Gavę 403, patikrinkite teises, IP apribojimus ir planą. Naujas žetonas neatkuria atšauktos prieigos.

Tapatybės patvirtinimas

Kartojimo taisyklės

Laikinas klaidas kartokite ribotą skaičių kartų su didėjančiu ir atsitiktiniu laukimo laiku.
Jei pateikiama Retry-After, jos laikykitės.
Pasibaigus įrašymo užklausos laukimo laikui, rezultatas gali būti nežinomas: kartodami tą pačią loginę operaciją išlaikykite tą patį Idempotency-Key ir nepakeistą užklausą.
Toliau pateiktas katalogas paaiškina visus paskelbtus klaidų kodus.

Saugus įrašymas

Užklausų dažnio ribos

422 / 409

Kainoms netinkamas valiutos formatas arba sumos tikslumas grąžina 422 request.validation_failed.
Galiojantis valiutos kodas, neatitinkantis pasirinkto kainoraščio, grąžina 409 resource.version_conflict.
Prieš bandydami dar kartą patikrinkite kontekstą ir versijas.

Klaidų katalogas

400request.malformedUžklausos negalima išanalizuoti.

Ką daryti: Patikrinkite JSON sintaksę, URL kodavimą ir užklausos struktūrą.
Kartojimo taisyklės: Kartokite pataisę užklausą.

JSON

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

401authentication.invalid_credentialsAPI raktas arba prieigos žetonas negalioja, jo galiojimas baigėsi arba jis atšauktas.

Ką daryti: Patikrinkite parduotuvės URL ir prieigos duomenis. Aktyviu API raktu gaukite naują žetoną.
Kartojimo taisyklės: Kartokite pataisę tapatybės patvirtinimą; nekartokite neteisingų žetono užklausų.

JSON

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

401authentication.requiredTrūksta būtinos Authorization antraštės arba jos schema neteisinga.

Ką daryti: Prašydami žetono naudokite ApiKey, o išteklių operacijoms – Bearer.
Kartojimo taisyklės: Kartokite pateikę tinkamą antraštę.

JSON

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

403authorization.client_ip_unverifiedPaslauga negalėjo nustatyti patikimo kliento IP adreso.

Ką daryti: Paprašykite parduotuvės operatoriaus patikrinti įeinančio ryšio kelią. Patys nepridėkite persiuntimo antraščių.
Kartojimo taisyklės: Kartokite atkūrus patikimą ryšio kelią.

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_allowedŠaltinio IP adresas nėra rakto leidžiamų adresų sąraše.

Ką daryti: Naudokite patvirtintą šaltinio adresą arba paprašykite įgalioto administratoriaus pakeisti rakto IP sąrašą.
Kartojimo taisyklės: Kartokite tik leidus šį adresą.

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_deniedRaktas neturi šiai operacijai reikalingos galiojančios teisės.

Ką daryti: Patikrinkite būtinas ir sąlygines operacijos teises, raktui suteiktas teises bei jį išdavusio asmens prieigą.
Kartojimo taisyklės: Kartokite, kai įgaliotas administratorius suteiks reikiamą prieigą.

JSON

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

403entitlements.api_disabledŠios parduotuvės API prieiga išjungta.

Ką daryti: Paprašykite parduotuvės savininko patikrinti aktyvų planą ir API prieinamumą.
Kartojimo taisyklės: Nekartokite, kol API prieiga neįjungta.

JSON

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

403entitlements.limit_exceededPakeitimas viršytų dabartinio plano ribą.

Ką daryti: Patikrinkite taikomą ištekliaus ribą ir pakoreguokite numatytą pakeitimą arba planą.
Kartojimo taisyklės: Kartokite išsprendę ribos problemą; pakeitę užklausą naudokite naują idempotentiškumo raktą.

JSON

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

403entitlements.operation_disabledDabartinis planas neapima šios operacijos.

Ką daryti: Patikrinkite operacijai nurodytą mažiausią planą.
Kartojimo taisyklės: Kartokite, kai planas leis operaciją ir raktas turės būtinas teises.

JSON

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

403entitlements.resource_blockedŠį konkretų išteklių blokuoja plano riba.

Ką daryti: Paprašykite savininko panaikinti ištekliui taikomą plano apribojimą.
Kartojimo taisyklės: Nekartokite tos pačios užklausos, kol išteklius užblokuotas.

JSON

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

404resource.not_foundIštekliaus nėra, jis pašalintas arba neprieinamas pagal pateiktą identifikatorių.

Ką daryti: Patikrinkite parduotuvę, ištekliaus kelią ir identifikatorių. Naudokite šios parduotuvės grąžintus identifikatorius.
Kartojimo taisyklės: Kartokite tik pataisę tikslą arba patvirtinę, kad jis egzistuoja.

JSON

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

405request.method_not_allowedPrieigos taškas nepalaiko šio HTTP metodo.

Ką daryti: Naudokite dokumentuotą metodą; Allow antraštė nurodo palaikomus metodus.
Kartojimo taisyklės: Nekartokite nepalaikomo metodo.

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_reusedŠis idempotentiškumo raktas priklauso kitai užklausai.

Ką daryti: Raskite pradinę operaciją. Naują raktą naudokite tik sąmoningai naujai loginei operacijai.
Kartojimo taisyklės: Nekartokite pakeistų duomenų su konfliktuojančiu raktu.

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_existsUnikali reikšmė konfliktuoja su esamu ištekliumi.

Ką daryti: Perskaitykite esamą išteklių ir nuspręskite, ar jį naudoti, ar pasirinkti kitą unikalią reikšmę.
Kartojimo taisyklės: Nekartokite to paties konfliktuojančio kūrimo.

JSON

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

409resource.in_useKiti ištekliai vis dar priklauso nuo šio ištekliaus.

Ką daryti: Peržiūrėkite priklausomybes ir prieš šalindami pašalinkite arba pakeiskite jas palaikomomis operacijomis.
Kartojimo taisyklės: Kartokite išsprendę priklausomybes.

JSON

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

409resource.state_conflictDabartinė verslo būsena neleidžia šio pakeitimo.

Ką daryti: Perskaitykite dabartinę būseną ir pasirinkite leidžiamą verslo būsenos perėjimą.
Kartojimo taisyklės: Neverskite sistemos taikyti konfliktuojančio pakeitimo ir nesiųskite jo pakartotinai automatiškai.

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_conflictKitas įrašymas pakeitė išteklių po to, kai perskaitėte jo versiją.

Ką daryti: Perskaitykite naujausią būseną, suderinkite pakeitimą ir pateikite naują expected_version.
Kartojimo taisyklės: Pakeistai operacijai naudokite naują idempotentiškumo raktą; neperrašykite duomenų nepatikrinę.

JSON

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

413request.too_largeUžklausa viršija dydžio ribą.

Ką daryti: Sumažinkite duomenis arba suskaidykite darbą į palaikomas atskiras operacijas.
Kartojimo taisyklės: Kartokite mažesnes tinkamas operacijas su atskirais jų idempotentiškumo raktais.

JSON

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

415request.unsupported_media_typeMedijos tipas arba turinio kodavimas nepalaikomas.

Ką daryti: JSON įrašymui naudokite Content-Type: application/json ir palaikomą nesuglaudintą turinį.
Kartojimo taisyklės: Kartokite pataisę medijos tipą arba kodavimą.

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_failedVienas ar keli laukai arba parametrai neatitiko tikrinimo taisyklių.

Ką daryti: Peržiūrėkite error.fields, tada patikrinkite būtinus laukus, null leidimą, identifikatorius ir leidžiamas reikšmes.
Kartojimo taisyklės: Kartokite pataisytą užklausą; pakeistas įrašymas yra nauja loginė operacija.

JSON

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

429capacity.queue_fullTrumpa API eilė pilna; užklausa dar nepradėta vykdyti.

Ką daryti: Dėkite užklausas į eilę ir laikykitės atsakymo antraštės Retry-After.
Kartojimo taisyklės: Palaukite bent Retry-After sekundžių ir pridėkite atsitiktinį delsos laiką. Kartodami įrašymą išlaikykite pradinį raktą ir duomenis.

JSON

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

429capacity.wait_timeoutBaigėsi laukimo API eilėje laikas; užklausa dar nepradėta vykdyti.

Ką daryti: Dėkite užklausas į eilę ir laikykitės atsakymo antraštės Retry-After.
Kartojimo taisyklės: Palaukite bent Retry-After sekundžių ir pridėkite atsitiktinį delsos laiką. Kartodami įrašymą išlaikykite pradinį raktą ir duomenis.

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.exceededUžklausų dažnis viršija taikomą ribą.

Ką daryti: Dėkite užklausas į eilę ir laikykitės atsakymo antraštės Retry-After.
Kartojimo taisyklės: Palaukite bent Retry-After sekundžių ir pridėkite atsitiktinį delsos laiką. Kartodami įrašymą išlaikykite pradinį raktą ir duomenis.

JSON

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

500internal.errorĮvyko netikėta paslaugos klaida.

Ką daryti: Užregistruokite užklausos identifikatorių; jei klaida kartojasi, kreipkitės į operatorių. Prisijungimo duomenų neįtraukite į žurnalus.
Kartojimo taisyklės: Taikykite ribotą didėjantį laukimo laiką. Įrašymui išlaikykite pradinį idempotentiškumo raktą ir nepakeistus duomenis.

JSON

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

502gateway.bad_responseTinklo šliuzas negavo galiojančio API atsakymo.

Ką daryti: Išsaugokite užklausos identifikatorių. Nesėkmingas atsakymas neįrodo, kad įrašymas nebuvo atliktas.
Kartojimo taisyklės: Taikykite ribotą didėjantį laukimo laiką; tą patį loginį įrašymą kartokite su pradiniu Idempotency-Key ir duomenimis.

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 laikinai negali apdoroti užklausos.

Ką daryti: Jei yra Retry-After, jos laikykitės; užsitęsus sutrikimui išsaugokite užklausos identifikatorių.
Kartojimo taisyklės: Taikykite ribotą didėjantį laukimo laiką su atsitiktine delsa; kartodami tą patį įrašymą išlaikykite raktą ir duomenis.

JSON

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

504gateway.timeoutTinklo šliuzui laukiant API baigėsi laukimo laikas.

Ką daryti: Išsaugokite užklausos identifikatorių ir laikykite įrašymo rezultatą nežinomu.
Kartojimo taisyklės: Taikykite ribotą didėjantį laukimo laiką; įrašymui išlaikykite pradinį idempotentiškumo raktą ir nepakeistus duomenis.

JSON

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