Chyby a obnovení provozu

Podle stabilních kódů chyb rozhodněte, zda požadavek opravit, vyčkat, nebo zopakovat.

Jak postupovat

Větvení programu založte na stavu HTTP a error.code, nikoli na textu error.message.
Stav 401 vyžaduje platné ověření; 403 změnu přístupu nebo tarifu; 409 kontrolu konfliktní operace nebo verze zdroje.

Odepřený přístup a opakování

401: 401 neznamená vždy vypršení tokenu. Pokud vypršel, získejte nový a čtení zopakujte nejvýše jednou. Pokud získání tokenu vrátí 401, zkontrolujte klíč a zastavte automatické pokusy.
403: Při 403 zkontrolujte oprávnění, omezení IP a tarif. Nový token neobnoví odebraný přístup.

Ověřování

Pravidla opakování

U dočasných chyb používejte omezený počet opakování s prodlužováním prodlevy a náhodným rozptylem.
Pokud odpověď obsahuje Retry-After, respektujte jej.
Při vypršení časového limitu zápisu nemusí být výsledek znám: při opakování stejné logické operace zachovejte Idempotency-Key i nezměněný požadavek.
Níže uvedený katalog vysvětluje všechny zveřejněné kódy chyb.

Bezpečné zápisy

Limity požadavků

422 / 409

U cen vrací neplatný formát měny nebo přesnost částky chybu 422 request.validation_failed.
Platný kód měny, který neodpovídá vybranému ceníku, vrací 409 resource.version_conflict.
Před opakováním zkontrolujte kontext a verze.

Katalog chyb

400request.malformedPožadavek nelze zpracovat kvůli nesprávné syntaxi.

Jak postupovat: Zkontrolujte syntaxi JSON, kódování URL a strukturu požadavku.
Pravidla opakování: Opakujte po opravě požadavku.

JSON

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

401authentication.invalid_credentialsKlíč API nebo přístupový token je neplatný, vypršel nebo byl odvolán.

Jak postupovat: Zkontrolujte URL obchodu a přístupový údaj. Pomocí aktivního klíče API získejte nový token.
Pravidla opakování: Opakujte až po opravě ověření; neposílejte opakovaně požadavky s neplatným tokenem.

JSON

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

401authentication.requiredChybí požadovaná hlavička Authorization nebo používá nesprávný způsob ověření.

Jak postupovat: Při získávání tokenu použijte ApiKey a při operacích se zdroji Bearer.
Pravidla opakování: Opakujte po doplnění správné 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 spolehlivě určit IP adresu klienta.

Jak postupovat: Požádejte provozovatele obchodu o kontrolu vstupní síťové cesty. Hlavičky předávání adres nevkládejte sami.
Pravidla opakování: Opakujte po obnovení důvěryhodné cesty připojení.

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 není v seznamu adres povolených pro tento klíč.

Jak postupovat: Použijte schválenou zdrojovou adresu nebo požádejte oprávněného správce o úpravu seznamu IP adres klíče.
Pravidla opakování: 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_deniedKlíč nemá účinné oprávnění vyžadované pro tuto operaci.

Jak postupovat: Zkontrolujte požadovaná a podmíněná oprávnění operace, oprávnění klíče a přístup jeho vydavatele.
Pravidla opakování: Opakujte, až oprávněný správce udělí potřebný přístup.

JSON

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

403entitlements.api_disabledPřístup k API je pro tento obchod vypnutý.

Jak postupovat: Požádejte vlastníka obchodu o kontrolu aktivního tarifu a dostupnosti API.
Pravidla opakování: Neopakujte, dokud nebude pří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_exceededZměna by překročila limit aktuálního tarifu.

Jak postupovat: Zkontrolujte příslušný limit zdroje a upravte zamýšlenou změnu nebo tarif.
Pravidla opakování: Opakujte po vyřešení limitu; při změně požadavku použijte nový klíč idempotence.

JSON

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

403entitlements.operation_disabledAktuální tarif tuto operaci nezahrnuje.

Jak postupovat: Zkontrolujte minimální tarif uvedený u operace.
Pravidla opakování: Opakujte, až tarif operaci umožní a klíč získá potřebná oprávnění.

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étní zdroj blokuje limit tarifu.

Jak postupovat: Požádejte vlastníka o vyřešení omezení zdroje vyplývajícího z tarifu.
Pravidla opakování: Stejný požadavek neopakujte, dokud zdroj zůstává 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 chybí, byl smazán nebo není dostupný pod zadaným identifikátorem.

Jak postupovat: Zkontrolujte obchod, cestu zdroje a identifikátor. Používejte identifikátory vrácené tímto obchodem.
Pravidla opakování: Opakujte až po opravě cíle nebo ověření jeho existence.

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 tuto metodu HTTP.

Jak postupovat: Použijte dokumentovanou metodu; hlavička Allow uvádí podporované metody.
Pravidla opakování: Nepodporovanou metodu 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 klíč idempotence patří jinému požadavku.

Jak postupovat: Vyhledejte původní operaci. Nový klíč použijte pouze pro záměrně novou logickou operaci.
Pravidla opakování: Neopakujte změněný obsah požadavku s konfliktním klíč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_existsJedinečná hodnota je v konfliktu s existujícím zdrojem.

Jak postupovat: Načtěte existující zdroj a rozhodněte, zda jej použít, nebo zvolit jinou jedinečnou hodnotu.
Pravidla opakování: Neopakujte stejné konfliktní vytvoření.

JSON

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

409resource.in_useNa tomto zdroji stále závisejí jiné zdroje.

Jak postupovat: Zkontrolujte závislosti a před smazáním je odstraňte nebo změňte pomocí podporovaných operací.
Pravidla opakování: Opakujte po vyřeš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ální obchodní stav tuto změnu neumožňuje.

Jak postupovat: Načtěte aktuální stav a zvolte platný přechod mezi stavy.
Pravidla opakování: Konfliktní změnu automaticky nevynucujte ani opakovaně neodesílejte.

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čtení vaší verze zdroj změnil jiný zápis.

Jak postupovat: Načtěte nejnovější stav, slaďte s ním svou změnu a odešlete novou expected_version.
Pravidla opakování: Pro upravenou operaci použijte nový klíč idempotence; data slepě nepřepisujte.

JSON

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

413request.too_largePožadavek překračuje limit velikosti.

Jak postupovat: Zmenšete obsah nebo rozdělte práci do podporovaných samostatných operací.
Pravidla opakování: Opakujte menší platné operace s jejich vlastními klíči idempotence.

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 nebo kódování obsahu není podporováno.

Jak postupovat: Pro zápisy JSON použijte Content-Type: application/json a podporované nekomprimované tělo.
Pravidla opakování: Opakujte po opravě typu média nebo kódování.

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 nebo více polí či parametrů neprošlo validací.

Jak postupovat: Prohlédněte error.fields a poté zkontrolujte povinná pole, možnost null, identifikátory a povolené hodnoty.
Pravidla opakování: Opakujte opravený požadavek; změněný zápis je nová logická operace.

JSON

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

429capacity.queue_fullKrátká fronta API je plná; požadavek se ještě nezačal provádět.

Jak postupovat: Zařaďte požadavky do fronty a respektujte hlavičku odpovědi Retry-After.
Pravidla opakování: Vyčkejte alespoň počet sekund z Retry-After a přidejte náhodnou prodlevu. Při opakování zápisu zachovejte původní klíč a obsah požadavku.

JSON

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

429capacity.wait_timeoutVypršela doba čekání ve frontě API; požadavek se ještě nezačal provádět.

Jak postupovat: Zařaďte požadavky do fronty a respektujte hlavičku odpovědi Retry-After.
Pravidla opakování: Vyčkejte alespoň počet sekund z Retry-After a přidejte náhodnou prodlevu. Při opakování zápisu zachovejte původní klíč a obsah požadavku.

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.exceededČetnost požadavků překračuje platný limit.

Jak postupovat: Zařaďte požadavky do fronty a respektujte hlavičku odpovědi Retry-After.
Pravidla opakování: Vyčkejte alespoň počet sekund z Retry-After a přidejte náhodnou prodlevu. Při opakování zápisu zachovejte původní klíč a obsah požadavku.

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čekávané chybě služby.

Jak postupovat: Zaznamenejte identifikátor požadavku a při přetrvávající chybě kontaktujte provozovatele; do protokolů nezapisujte přístupové údaje.
Pravidla opakování: Použijte omezený počet opakování s rostoucí prodlevou. U zápisu zachovejte původní klíč idempotence a nezměněný obsah požadavku.

JSON

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

502gateway.bad_responseBrána neobdržela platnou odpověď API.

Jak postupovat: Uchovejte identifikátor požadavku. Chybná odpověď nedokazuje, že zápis nebyl proveden.
Pravidla opakování: Použijte omezený počet opakování s rostoucí prodlevou; stejný logický zápis opakujte s původním Idempotency-Key a obsahem požadavku.

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časně nemůže požadavek obsloužit.

Jak postupovat: Respektujte Retry-After, pokud je uvedeno, a při delším výpadku uchovejte identifikátor požadavku.
Pravidla opakování: Použijte omezený počet opakování s rostoucí a náhodnou prodlevou; při opakování stejného zápisu zachovejte klíč a obsah požadavku.

JSON

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

504gateway.timeoutBráně při čekání na API vypršel časový limit.

Jak postupovat: Uchovejte identifikátor požadavku a výsledek zápisu považujte za neznámý.
Pravidla opakování: Použijte omezený počet opakování s rostoucí prodlevou; u zápisu zachovejte původní klíč idempotence a nezměněný obsah požadavku.

JSON

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