Chyby a obnovenie prevádzky

Podľa stabilných kódov chýb rozhodnite, či požiadavku opraviť, počkať alebo zopakovať.

Ako postupovať

Vetvenie programu založte na stave HTTP a error.code, nie na texte error.message.
Stav 401 vyžaduje platné overenie; 403 zmenu prístupu alebo plánu; 409 kontrolu konfliktnej operácie alebo verzie zdroja.

Odmietnutý prístup a opakovanie

401: 401 neznamená vždy vypršanie tokenu. Ak vypršal, získajte nový a čítanie zopakujte najviac raz. Ak získanie tokenu vráti 401, skontrolujte kľúč a zastavte automatické pokusy.
403: Pri 403 skontrolujte oprávnenia, obmedzenia IP a plán. Nový token neobnoví odobratý prístup.

Overovanie

Pravidlá opakovania

Pri dočasných chybách používajte obmedzený počet opakovaní s predlžovaním oneskorenia a náhodným rozptylom.
Ak odpoveď obsahuje Retry-After, rešpektujte ho.
Pri vypršaní časového limitu zápisu nemusí byť výsledok známy: pri opakovaní rovnakej logickej operácie zachovajte Idempotency-Key aj nezmenenú požiadavku.
Nasledujúci katalóg vysvetľuje všetky zverejnené kódy chýb.

Bezpečné zápisy

Limity požiadaviek

422 / 409

Pri cenách vracia neplatný formát meny alebo presnosť sumy chybu 422 request.validation_failed.
Platný kód meny, ktorý nezodpovedá vybranému cenníku, vracia 409 resource.version_conflict.
Pred opakovaním skontrolujte kontext a verzie.

Katalóg chýb

400request.malformedPožiadavku nemožno spracovať pre nesprávnu syntax.

Ako postupovať: Skontrolujte syntax JSON, kódovanie URL a štruktúru požiadavky.
Pravidlá opakovania: Opakujte po oprave požiadavky.

JSON

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

401authentication.invalid_credentialsKľúč API alebo prístupový token je neplatný, vypršal alebo bol odvolaný.

Ako postupovať: Skontrolujte URL obchodu a prístupový údaj. Pomocou aktívneho kľúča API získajte nový token.
Pravidlá opakovania: Opakujte až po oprave overenia; neposielajte opakovane požiadavky s neplatným tokenom.

JSON

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

401authentication.requiredChýba požadovaná hlavička Authorization alebo používa nesprávny spôsob overenia.

Ako postupovať: Pri získavaní tokenu použite ApiKey a pri operáciách so zdrojmi Bearer.
Pravidlá opakovania: Opakujte po doplnení správnej hlavičky.

JSON

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

403authorization.client_ip_unverifiedSlužba nedokázala spoľahlivo určiť IP adresu klienta.

Ako postupovať: Požiadajte prevádzkovateľa obchodu o kontrolu vstupnej sieťovej cesty. Hlavičky odovzdávania adries nevkladajte sami.
Pravidlá opakovania: Opakujte po obnovení dôveryhodnej cesty pripojenia.

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_allowedZdrojová IP adresa nie je v zozname adries povolených pre tento kľúč.

Ako postupovať: Použite schválenú zdrojovú adresu alebo požiadajte oprávneného správcu o úpravu zoznamu IP adries kľúča.
Pravidlá opakovania: Opakujte až po povolení adresy.

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_deniedKľúč nemá účinné oprávnenie vyžadované pre túto operáciu.

Ako postupovať: Skontrolujte požadované a podmienené oprávnenia operácie, oprávnenia kľúča a prístup jeho vydavateľa.
Pravidlá opakovania: Opakujte, keď oprávnený správca udelí potrebný prístup.

JSON

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

403entitlements.api_disabledPrístup k API je pre tento obchod vypnutý.

Ako postupovať: Požiadajte vlastníka obchodu o kontrolu aktívneho plánu a dostupnosti API.
Pravidlá opakovania: Neopakujte, kým nebude prístup k API zapnutý.

JSON

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

403entitlements.limit_exceededZmena by prekročila limit aktuálneho plánu.

Ako postupovať: Skontrolujte príslušný limit zdroja a upravte zamýšľanú zmenu alebo plán.
Pravidlá opakovania: Opakujte po vyriešení limitu; pri zmene požiadavky použite nový kľúč idempotencie.

JSON

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

403entitlements.operation_disabledAktuálny plán túto operáciu nezahŕňa.

Ako postupovať: Skontrolujte minimálny plán uvedený pri operácii.
Pravidlá opakovania: Opakujte, keď plán operáciu umožní a kľúč získa potrebné oprávnenia.

JSON

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

403entitlements.resource_blockedTento konkrétny zdroj blokuje limit plánu.

Ako postupovať: Požiadajte vlastníka o vyriešenie obmedzenia zdroja vyplývajúceho z plánu.
Pravidlá opakovania: Rovnakú požiadavku neopakujte, kým zdroj zostáva blokovaný.

JSON

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

404resource.not_foundZdroj chýba, bol zmazaný alebo nie je dostupný pod zadaným identifikátorom.

Ako postupovať: Skontrolujte obchod, cestu zdroja a identifikátor. Používajte identifikátory vrátené týmto obchodom.
Pravidlá opakovania: Opakujte až po oprave cieľa alebo overení jeho existencie.

JSON

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

405request.method_not_allowedKoncový bod nepodporuje túto metódu HTTP.

Ako postupovať: Použite dokumentovanú metódu; hlavička Allow uvádza podporované metódy.
Pravidlá opakovania: Nepodporovanú metódu neopakujte.

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_reusedTento kľúč idempotencie patrí inej požiadavke.

Ako postupovať: Vyhľadajte pôvodnú operáciu. Nový kľúč použite iba pre zámerne novú logickú operáciu.
Pravidlá opakovania: Neopakujte zmenený obsah požiadavky s konfliktným kľúčom.

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_existsJedinečná hodnota je v konflikte s existujúcim zdrojom.

Ako postupovať: Načítajte existujúci zdroj a rozhodnite, či ho použiť alebo zvoliť inú jedinečnú hodnotu.
Pravidlá opakovania: Neopakujte rovnaké konfliktné vytvorenie.

JSON

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

409resource.in_useOd tohto zdroja stále závisia iné zdroje.

Ako postupovať: Skontrolujte závislosti a pred zmazaním ich odstráňte alebo zmeňte pomocou podporovaných operácií.
Pravidlá opakovania: Opakujte po vyriešení závislostí.

JSON

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

409resource.state_conflictAktuálny obchodný stav túto zmenu neumožňuje.

Ako postupovať: Načítajte aktuálny stav a vyberte platný prechod medzi stavmi.
Pravidlá opakovania: Konfliktnú zmenu automaticky nevynucujte ani opakovane neodosielajte.

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_conflictPo načítaní vašej verzie zdroj zmenil iný zápis.

Ako postupovať: Načítajte najnovší stav, zosúlaďte s ním svoju zmenu a odošlite novú expected_version.
Pravidlá opakovania: Pre upravenú operáciu použite nový kľúč idempotencie; údaje slepo neprepisujte.

JSON

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

413request.too_largePožiadavka prekračuje limit veľkosti.

Ako postupovať: Zmenšite obsah alebo rozdeľte prácu na podporované samostatné operácie.
Pravidlá opakovania: Opakujte menšie platné operácie s ich vlastnými kľúčmi idempotencie.

JSON

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

415request.unsupported_media_typeTyp média alebo kódovanie obsahu nie je podporované.

Ako postupovať: Pre zápisy JSON použite Content-Type: application/json a podporované nekomprimované telo.
Pravidlá opakovania: Opakujte po oprave typu média alebo kódovania.

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 alebo viac polí či parametrov neprešlo validáciou.

Ako postupovať: Prezrite error.fields a potom skontrolujte povinné polia, možnosť null, identifikátory a povolené hodnoty.
Pravidlá opakovania: Opakujte opravenú požiadavku; zmenený zápis je nová logická operácia.

JSON

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

429capacity.queue_fullKrátky rad API je plný; požiadavka sa ešte nezačala vykonávať.

Ako postupovať: Zaraďte požiadavky do frontu a rešpektujte hlavičku odpovede Retry-After.
Pravidlá opakovania: Počkajte aspoň počet sekúnd z Retry-After a pridajte náhodné oneskorenie. Pri opakovaní zápisu zachovajte pôvodný kľúč a obsah požiadavky.

JSON

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

429capacity.wait_timeoutUplynul čas čakania v rade API; požiadavka sa ešte nezačala vykonávať.

Ako postupovať: Zaraďte požiadavky do frontu a rešpektujte hlavičku odpovede Retry-After.
Pravidlá opakovania: Počkajte aspoň počet sekúnd z Retry-After a pridajte náhodné oneskorenie. Pri opakovaní zápisu zachovajte pôvodný kľúč a obsah požiadavky.

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.exceededFrekvencia požiadaviek prekračuje platný limit.

Ako postupovať: Zaraďte požiadavky do frontu a rešpektujte hlavičku odpovede Retry-After.
Pravidlá opakovania: Počkajte aspoň počet sekúnd z Retry-After a pridajte náhodné oneskorenie. Pri opakovaní zápisu zachovajte pôvodný kľúč a obsah požiadavky.

JSON

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

500internal.errorDošlo k neočakávanej chybe služby.

Ako postupovať: Zaznamenajte identifikátor požiadavky a pri pretrvávajúcej chybe kontaktujte prevádzkovateľa; do protokolov nezapisujte prístupové údaje.
Pravidlá opakovania: Použite obmedzený počet opakovaní s rastúcim oneskorením. Pri zápise zachovajte pôvodný kľúč idempotencie a nezmenený obsah požiadavky.

JSON

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

502gateway.bad_responseBrána nedostala platnú odpoveď API.

Ako postupovať: Uchovajte identifikátor požiadavky. Chybná odpoveď nedokazuje, že zápis nebol vykonaný.
Pravidlá opakovania: Použite obmedzený počet opakovaní s rastúcim oneskorením; rovnaký logický zápis opakujte s pôvodným Idempotency-Key a obsahom požiadavky.

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 dočasne nedokáže požiadavku obslúžiť.

Ako postupovať: Rešpektujte Retry-After, ak je uvedené, a pri dlhšom výpadku uchovajte identifikátor požiadavky.
Pravidlá opakovania: Použite obmedzený počet opakovaní s rastúcim a náhodným oneskorením; pri opakovaní rovnakého zápisu zachovajte kľúč a obsah požiadavky.

JSON

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

504gateway.timeoutBráne pri čakaní na API vypršal časový limit.

Ako postupovať: Uchovajte identifikátor požiadavky a výsledok zápisu považujte za neznámy.
Pravidlá opakovania: Použite obmedzený počet opakovaní s rastúcim oneskorením; pri zápise zachovajte pôvodný kľúč idempotencie a nezmenený obsah požiadavky.

JSON

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