Greške i oporavak

Koristite stabilne kodove grešaka da biste odlučili treba li ispraviti zahtev, pričekati ili ponoviti.

Šta uraditi

Logiku temeljite na HTTP statusu i error.code, a ne na tekstu error.message.
Status 401 zahteva valjanu autentifikaciju; 403 zahteva promenu pristupa ili plana; 409 zahteva proveru operacije u sukobu ili verzije resursa.

Odbijen pristup i ponovni pokušaji

401: 401 ne znači uvek da je token istekao. Ako je istekao, preuzmite novi i ponovite čitanje najviše jednom. Ako preuzimanje tokena vrati 401, proverite ključ i zaustavite automatske pokušaje.
403: Za 403 proverite dozvole, IP ograničenja i plan. Novi token ne vraća opozvani pristup.

Autentifikacija

Pravila ponavljanja

Za privremene greške koristite ograničen broj ponavljanja s rastućim i nasumičnim razmakom.
Poštujte Retry-After kada je naveden.
Ako upis prekorači vreme čekanja, njegov ishod može biti nepoznat: pri ponavljanju iste logičke operacije zadržite isti Idempotency-Key i nepromenjen zahtev.
Katalog u nastavku objašnjava svaki objavljeni kod greške.

Sigurni upisi

Ograničenja učestalosti

422 / 409

Za cene neispravan format valute ili preciznost iznosa vraćaju 422 request.validation_failed.
Važeći kod valute koji ne odgovara izabranom cenovniku vraća 409 resource.version_conflict.
Pre ponovnog pokušaja proverite kontekst i verzije.

Katalog grešaka

400request.malformedZahtev se ne može parsirati.

Šta uraditi: Proverite JSON sintaksu, kodiranje URL-a i strukturu zahteva.
Pravila ponavljanja: Ponovite nakon ispravka zahteva.

JSON

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

401authentication.invalid_credentialsAPI ključ ili pristupni token nije valjan, istekao je ili je opozvan.

Šta uraditi: Proverite URL prodavnice i akreditiv. Dohvatite novi token aktivnim API ključem.
Pravila ponavljanja: Ponovite nakon ispravka autentifikacije; izbegavajte ponavljane nevaljane zahteve za token.

JSON

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

401authentication.requiredNedostaje obavezno zaglavlje Authorization ili njegova šema nije ispravna.

Šta uraditi: Koristite ApiKey pri traženju tokena i Bearer za operacije s resursima.
Pravila ponavljanja: Ponovite nakon slanja ispravnog zaglavlja.

JSON

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

403authorization.client_ip_unverifiedUsluga nije mogla pouzdano utvrditi IP adresu klijenta.

Šta uraditi: Zatražite od operatera prodavnice da proveri ulaznu putanju. Nemojte sami dodavati zaglavlja za prosleđivanje.
Pravila ponavljanja: Ponovite nakon obnove pouzdane putanje veze.

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_allowedIzvorna IP adresa nije na spisku dozvoljenih adresa ključa.

Šta uraditi: Koristite odobrenu izvornu adresu ili zatražite od ovlašćenog administratora da uredi IP spisak ključa.
Pravila ponavljanja: Ponovite tek nakon što adresa bude dozvoljena.

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č nema važeće ovlašćenje potrebno za ovu operaciju.

Šta uraditi: Proverite obavezna i uslovna ovlašćenja operacije, ovlašćenja ključa i pristup izdavaoca.
Pravila ponavljanja: Ponovite nakon što ovlašćeni administrator dodeli potreban pristup.

JSON

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

403entitlements.api_disabledAPI pristup isključen je za ovu prodavnicu.

Šta uraditi: Zatražite od vlasnika prodavnice da proveri aktivni plan i dostupnost API-ja.
Pravila ponavljanja: Ne ponavljajte dok se API pristup ne uključi.

JSON

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

403entitlements.limit_exceededPromena bi prekoračila ograničenje trenutnog plana.

Šta uraditi: Proverite primenjivo ograničenje resursa i prilagodite željenu promenu ili plan.
Pravila ponavljanja: Ponovite nakon rešavanja ograničenja; ako se zahtev promeni, koristite novi 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 plan ne uključuje ovu operaciju.

Šta uraditi: Proverite minimalni plan naveden za operaciju.
Pravila ponavljanja: Ponovite nakon što plan dozvoljava operaciju i ključ ima potrebna ovlašćenja.

JSON

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

403entitlements.resource_blockedOgraničenje plana blokira ovaj resurs.

Šta uraditi: Zatražite od vlasnika da reši ograničenje plana za taj resurs.
Pravila ponavljanja: Ne ponavljajte isti zahtev dok je resurs 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_foundResurs ne postoji, izbrisan je ili nije dostupan pod navedenim identifikatorom.

Šta uraditi: Proverite prodavnicu, putanju resursa i identifikator. Koristite identifikatore koje je vratila ova prodavnica.
Pravila ponavljanja: Ponovite tek nakon ispravka cilja ili potvrde da postoji.

JSON

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

405request.method_not_allowedKrajnja tačka ne podržava ovu HTTP metodu.

Šta uraditi: Koristite dokumentovanu metodu; zaglavlje Allow navodi podržane metode.
Pravila ponavljanja: Ne ponavljajte nepodržanu metodu.

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_reusedOvaj ključ idempotentnosti pripada drugom zahtevu.

Šta uraditi: Pronađite izvornu operaciju. Koristite novi ključ samo za namerno novu logičku operaciju.
Pravila ponavljanja: Ne ponavljajte promenjene podatke s ključem koji izaziva sukob.

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_existsJedinstvena vrednost u sukobu je s postojećim resursom.

Šta uraditi: Pročitajte postojeći resurs i odlučite hoćete li ga koristiti ili odabrati drugu jedinstvenu vrednost.
Pravila ponavljanja: Ne ponavljajte isto kreiranje koje izaziva sukob.

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 resursi i dalje zavise o ovom resursu.

Šta uraditi: Pregledajte zavisnosti i uklonite ih ili promenite podržanim operacijama pre brisanja.
Pravila ponavljanja: Ponovite nakon rešavanja zavisnosti.

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 sprečava ovu promenu.

Šta uraditi: Pročitajte trenutno stanje i odaberite valjan poslovni prelaz.
Pravila ponavljanja: Nemojte automatski nametati ni opetovano slati promenu koja izaziva sukob.

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_conflictDrugi upis promenio je resurs nakon verzije koju ste pročitali.

Šta uraditi: Pročitajte najnovije stanje, uskladite promenu i pošaljite novu expected_version.
Pravila ponavljanja: Koristite novi ključ idempotentnosti za izmenjenu operaciju; nemojte naslepo prepisivati podatke.

JSON

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

413request.too_largeZahtev prekoračuje ograničenje veličine.

Šta uraditi: Smanjite podatke ili podelite posao na podržane pojedinačne operacije.
Pravila ponavljanja: Ponovite manje valjane operacije sa posebnim ključevima 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 sadržaja ili kodiranje sadržaja nije podržano.

Šta uraditi: Za JSON upise koristite Content-Type: application/json i podržano nekomprimirano telo.
Pravila ponavljanja: Ponovite nakon ispravka vrste ili kodiranja sadržaja.

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_failedJedno ili više polja ili parametara ne prolazi proveru valjanosti.

Šta uraditi: Pregledajte error.fields, a zatim proverite obavezna polja, dozvoljavanje null, identifikatore i dozvoljene vrednosti.
Pravila ponavljanja: Ponovite ispravljen zahtev; promenjeni upis nova je logička operacija.

JSON

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

429capacity.queue_fullKratki red čekanja API-ja je pun; izvršavanje zahteva nije počelo.

Šta uraditi: Stavite zahteve u red čekanja i poštujte zaglavlje odgovora Retry-After.
Pravila ponavljanja: Pričekajte najmanje Retry-After sekundi i dodajte nasumični razmak. Pri ponavljanju upisa zadržite izvorni ključ i podatke.

JSON

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

429capacity.wait_timeoutIsteklo je vreme čekanja u redu API-ja; izvršavanje zahteva nije počelo.

Šta uraditi: Stavite zahteve u red čekanja i poštujte zaglavlje odgovora Retry-After.
Pravila ponavljanja: Pričekajte najmanje Retry-After sekundi i dodajte nasumični razmak. Pri ponavljanju upisa zadržite izvorni ključ i 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.exceededUčestalost zahteva prekoračuje primenjivo ograničenje.

Šta uraditi: Stavite zahteve u red čekanja i poštujte zaglavlje odgovora Retry-After.
Pravila ponavljanja: Pričekajte najmanje Retry-After sekundi i dodajte nasumični razmak. Pri ponavljanju upisa zadržite izvorni ključ i podatke.

JSON

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

500internal.errorDošlo je do neočekivane greške usluge.

Šta uraditi: Zabeležite identifikator zahteva i obratite se operateru ako se greška nastavi; ne uključujte akreditive u dnevnike.
Pravila ponavljanja: Koristite ograničeno ponavljanje uz rastuće čekanje. Za upis zadržite izvorni ključ idempotentnosti i nepromenjene podatke.

JSON

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

502gateway.bad_responseMrežni prolaz nije primio valjan API odgovor.

Šta uraditi: Sačuvajte identifikator zahteva. Neuspešan odgovor ne dokazuje da upis nije primenjen.
Pravila ponavljanja: Koristite ograničeno ponavljanje uz rastuće čekanje; ponovite isti logički upis s izvornim Idempotency-Key i nepromenjenim podacima.

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 privremeno ne može obraditi zahtev.

Šta uraditi: Poštujte Retry-After kada postoji i sačuvajte identifikator zahteva ako prekid potraje.
Pravila ponavljanja: Koristite ograničeno ponavljanje s rastućim i nasumičnim čekanjem; pri ponavljanju istog upisa zadržite ključ i podatke.

JSON

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

504gateway.timeoutMrežni prolaz je prekoračio vreme čekanja na API.

Šta uraditi: Sačuvajte identifikator zahteva i smatrajte ishod upisa nepoznatim.
Pravila ponavljanja: Koristite ograničeno ponavljanje uz rastuće čekanje; za upis zadržite izvorni ključ idempotentnosti i nepromenjene podatke.

JSON

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