Pogreške i oporavak

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

Što učiniti

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

Odbijen pristup i ponovni pokušaji

401: 401 ne znači uvijek da je token istekao. Ako je istekao, dohvatite novi i ponovite čitanje najviše jednom. Ako dohvat tokena vrati 401, provjerite ključ i zaustavite automatske pokušaje.
403: Za 403 provjerite ovlasti, IP ograničenja i plan. Novi token ne vraća opozvani pristup.

Autentifikacija

Pravila ponavljanja

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

Sigurni upisi

Ograničenja učestalosti

422 / 409

Za cijene neispravan format valute ili preciznost iznosa vraćaju 422 request.validation_failed.
Valjan kod valute koji ne odgovara odabranom cjeniku vraća 409 resource.version_conflict.
Prije ponovnog pokušaja provjerite kontekst i verzije.

Katalog pogrešaka

400request.malformedZahtjev se ne može parsirati.

Što učiniti: Provjerite JSON sintaksu, kodiranje URL-a i strukturu zahtjeva.
Pravila ponavljanja: Ponovite nakon ispravka zahtjeva.

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.

Što učiniti: Provjerite URL trgovine i vjerodajnicu. Dohvatite novi token aktivnim API ključem.
Pravila ponavljanja: Ponovite nakon ispravka autentifikacije; izbjegavajte ponavljane nevaljane zahtjeve za token.

JSON

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

401authentication.requiredNedostaje obvezno zaglavlje Authorization ili njegova shema nije ispravna.

Što učiniti: 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.

Što učiniti: Zatražite od operatera trgovine da provjeri ulaznu putanju. Nemojte sami dodavati zaglavlja za prosljeđ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 popisu dopuštenih adresa ključa.

Što učiniti: Koristite odobrenu izvornu adresu ili zatražite od ovlaštenog administratora da uredi IP popis ključa.
Pravila ponavljanja: Ponovite tek nakon što adresa bude dopuštena.

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ću ovlast potrebnu za ovu operaciju.

Što učiniti: Provjerite obvezne i uvjetne ovlasti operacije, ovlasti ključa i pristup izdavatelja.
Pravila ponavljanja: Ponovite nakon što ovlašteni administrator dodijeli 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 trgovinu.

Što učiniti: Zatražite od vlasnika trgovine da provjeri 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_exceededPromjena bi prekoračila ograničenje trenutačnog plana.

Što učiniti: Provjerite primjenjivo ograničenje resursa i prilagodite željenu promjenu ili plan.
Pravila ponavljanja: Ponovite nakon rješavanja ograničenja; ako se zahtjev promijeni, 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_disabledTrenutačni plan ne uključuje ovu operaciju.

Što učiniti: Provjerite minimalni plan naveden za operaciju.
Pravila ponavljanja: Ponovite nakon što plan dopušta operaciju i ključ ima potrebne ovlasti.

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.

Što učiniti: Zatražite od vlasnika da riješi ograničenje plana za taj resurs.
Pravila ponavljanja: Ne ponavljajte isti zahtjev 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.

Što učiniti: Provjerite trgovinu, putanju resursa i identifikator. Koristite identifikatore koje je vratila ova trgovina.
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 točka ne podržava ovu HTTP metodu.

Što učiniti: Koristite dokumentiranu 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 zahtjevu.

Što učiniti: Pronađite izvornu operaciju. Koristite novi ključ samo za namjerno novu logičku operaciju.
Pravila ponavljanja: Ne ponavljajte promijenjene 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 vrijednost u sukobu je s postojećim resursom.

Što učiniti: Pročitajte postojeći resurs i odlučite hoćete li ga koristiti ili odabrati drugu jedinstvenu vrijednost.
Pravila ponavljanja: Ne ponavljajte istu izradu koja 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 ovise o ovom resursu.

Što učiniti: Pregledajte ovisnosti i uklonite ih ili promijenite podržanim operacijama prije brisanja.
Pravila ponavljanja: Ponovite nakon rješavanja ovisnosti.

JSON

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

409resource.state_conflictTrenutačno poslovno stanje sprečava ovu promjenu.

Što učiniti: Pročitajte trenutačno stanje i odaberite valjan poslovni prijelaz.
Pravila ponavljanja: Nemojte automatski nametati ni opetovano slati promjenu 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 promijenio je resurs nakon verzije koju ste pročitali.

Što učiniti: Pročitajte najnovije stanje, uskladite promjenu i pošaljite novu expected_version.
Pravila ponavljanja: Koristite novi ključ idempotentnosti za izmijenjenu operaciju; nemojte naslijepo prepisivati podatke.

JSON

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

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

Što učiniti: Smanjite podatke ili podijelite posao na podržane pojedinačne operacije.
Pravila ponavljanja: Ponovite manje valjane operacije sa zasebnim 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.

Što učiniti: Za JSON upise koristite Content-Type: application/json i podržano nekomprimirano tijelo.
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 provjeru valjanosti.

Što učiniti: Pregledajte error.fields, a zatim provjerite obvezna polja, dopuštanje null, identifikatore i dopuštene vrijednosti.
Pravila ponavljanja: Ponovite ispravljen zahtjev; promijenjeni 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 zahtjeva nije započelo.

Što učiniti: Stavite zahtjeve 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 vrijeme čekanja u redu API-ja; izvršavanje zahtjeva nije započelo.

Što učiniti: Stavite zahtjeve 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 zahtjeva prekoračuje primjenjivo ograničenje.

Što učiniti: Stavite zahtjeve 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 pogreške usluge.

Što učiniti: Zabilježite identifikator zahtjeva i obratite se operateru ako se pogreška nastavi; ne uključujte vjerodajnice u zapisnike.
Pravila ponavljanja: Koristite ograničeno ponavljanje uz rastuće čekanje. Za upis zadržite izvorni ključ idempotentnosti i nepromijenjene podatke.

JSON

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

502gateway.bad_responsePristupnik nije primio valjan API odgovor.

Što učiniti: Sačuvajte identifikator zahtjeva. Neuspješan odgovor ne dokazuje da upis nije primijenjen.
Pravila ponavljanja: Koristite ograničeno ponavljanje uz rastuće čekanje; ponovite isti logički upis s izvornim Idempotency-Key i nepromijenjenim 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 zahtjev.

Što učiniti: Poštujte Retry-After kada postoji i sačuvajte identifikator zahtjeva 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.timeoutPristupnik je prekoračio vrijeme čekanja na API.

Što učiniti: Sačuvajte identifikator zahtjeva i smatrajte ishod upisa nepoznatim.
Pravila ponavljanja: Koristite ograničeno ponavljanje uz rastuće čekanje; za upis zadržite izvorni ključ idempotentnosti i nepromijenjene podatke.

JSON

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