Hibák és helyreállítás

A stabil hibakódok alapján döntse el, hogy javításra, várakozásra vagy újrapróbálásra van szükség.

Teendő

A program logikája a HTTP-állapotra és az error.code értékére támaszkodjon, ne az embernek szánt error.message szövegére.
A 401 érvényes hitelesítést, a 403 hozzáférési vagy csomagmódosítást, a 409 pedig az ütköző művelet vagy erőforrás-verzió ellenőrzését igényli.

Hozzáférés megtagadva és újrapróbálkozás

401: A 401 nem mindig jelenti a token lejártát. Ha lejárt, kérjen újat, és az olvasást legfeljebb egyszer ismételje meg. Ha a tokenkérés 401-et ad vissza, ellenőrizze a kulcsot, és állítsa le az automatikus próbálkozásokat.
403: 403 esetén ellenőrizze a jogosultságokat, az IP-korlátozásokat és a csomagot. Az új token nem állítja vissza a visszavont hozzáférést.

Hitelesítés

Újrapróbálási szabály

Átmeneti hibáknál korlátozott számú újrapróbálást használjon növekvő várakozással és véletlenszerű időeltolással.
Vegye figyelembe a Retry-After fejlécet.
Ha egy írás időtúllépéssel zárul, az eredménye ismeretlen lehet: ugyanazt az Idempotency-Key értéket és változatlan kérést használja az ismétléshez.
Az alábbi katalógus minden közzétett hibakódot ismertet.

Biztonságos írások

Kéréskorlátok

422 / 409

Áraknál az érvénytelen pénznemformátum vagy az összeg nem megfelelő pontossága 422 request.validation_failed hibát ad.
A kiválasztott árlistától eltérő, de érvényes pénznemkód 409 resource.version_conflict hibát ad.
Újrapróbálkozás előtt ellenőrizd a kontextust és a verziókat.

Hibakatalógus

400request.malformedA kérés nem értelmezhető.

Teendő: Ellenőrizze a JSON szintaxisát, az URL-kódolást és a kérés szerkezetét.
Újrapróbálási szabály: A kérés javítása után próbálkozzon újra.

JSON

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

401authentication.invalid_credentialsAz API-kulcs vagy hozzáférési token érvénytelen, lejárt vagy visszavonták.

Teendő: Ellenőrizze az áruház URL-jét és a hitelesítő adatot. Aktív API-kulccsal kérjen új tokent.
Újrapróbálási szabály: A hitelesítés javítása után próbálkozzon újra; kerülje az érvénytelen tokenkérések ismétlését.

JSON

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

401authentication.requiredHiányzik a kötelező Authorization fejléc, vagy hibás a hitelesítési sémája.

Teendő: Tokenkéréshez ApiKey, erőforrás-műveletekhez Bearer sémát használjon.
Újrapróbálási szabály: A megfelelő fejléc megadása után próbálkozzon újra.

JSON

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

403authorization.client_ip_unverifiedA szolgáltatás nem tudott megbízható kliens-IP-címet megállapítani.

Teendő: Kérje az áruház üzemeltetőjét a bejövő kapcsolat útvonalának ellenőrzésére. Ne adjon meg saját továbbítási fejléceket.
Újrapróbálási szabály: A megbízható kapcsolati útvonal helyreállítása után próbálkozzon újra.

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_allowedA forrás IP-címe nem szerepel a kulcs engedélyezett címei között.

Teendő: Használjon jóváhagyott forráscímet, vagy kérjen meg egy jogosult rendszergazdát a kulcs IP-listájának módosítására.
Újrapróbálási szabály: Csak a cím engedélyezése után próbálkozzon újra.

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_deniedA kulcsnak nincs meg a művelethez szükséges érvényes jogosultsága.

Teendő: Ellenőrizze a művelet kötelező és feltételes jogosultságait, a kulcs engedélyeit és a kibocsátó hozzáférését.
Újrapróbálási szabály: A szükséges hozzáférés jogosult rendszergazda általi megadása után próbálkozzon újra.

JSON

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

403entitlements.api_disabledAz API-hozzáférés le van tiltva ebben az áruházban.

Teendő: Kérje az áruház tulajdonosát az aktív csomag és az API elérhetőségének ellenőrzésére.
Újrapróbálási szabály: Az API-hozzáférés engedélyezéséig ne próbálkozzon újra.

JSON

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

403entitlements.limit_exceededA módosítás túllépné az aktuális csomag valamelyik korlátját.

Teendő: Ellenőrizze az érintett erőforrás korlátját, és módosítsa a tervezett változtatást vagy a csomagot.
Újrapróbálási szabály: A korlát rendezése után próbálkozzon újra; módosított kéréshez új idempotenciakulcsot használjon.

JSON

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

403entitlements.operation_disabledAz aktuális csomag nem tartalmazza ezt a műveletet.

Teendő: Ellenőrizze a műveletnél megadott minimális csomagot.
Újrapróbálási szabály: Akkor próbálkozzon újra, ha a csomag már engedi a műveletet, és a kulcsnak megvannak a szükséges jogosultságai.

JSON

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

403entitlements.resource_blockedEzt az erőforrást egy csomagkorlát blokkolja.

Teendő: Kérje a tulajdonost az erőforrás csomagkorlátozásának rendezésére.
Újrapróbálási szabály: Amíg az erőforrás blokkolt, ne ismételje ugyanazt a kérést.

JSON

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

404resource.not_foundAz erőforrás nem létezik, törölték, vagy a megadott azonosítóval nem érhető el.

Teendő: Ellenőrizze az áruházat, az erőforrás útvonalát és az azonosítót. Az adott áruház által visszaadott azonosítókat használja.
Újrapróbálási szabály: Csak a cél javítása vagy létezésének ellenőrzése után próbálkozzon újra.

JSON

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

405request.method_not_allowedA végpont nem támogatja ezt a HTTP-metódust.

Teendő: Használja a dokumentált metódust; az Allow fejléc felsorolja a támogatott metódusokat.
Újrapróbálási szabály: A nem támogatott metódussal ne próbálkozzon újra.

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_reusedEz az idempotenciakulcs egy másik kéréshez tartozik.

Teendő: Keresse meg az eredeti műveletet. Új kulcsot csak szándékosan új logikai művelethez használjon.
Újrapróbálási szabály: Az ütköző kulccsal ne próbáljon módosított adatokat újraküldeni.

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_existsEgy egyedi érték ütközik egy meglévő erőforrással.

Teendő: Olvassa ki a meglévő erőforrást, és döntse el, hogy azt használja-e, vagy más egyedi értéket választ.
Újrapróbálási szabály: Ne ismételje ugyanazt az ütköző létrehozást.

JSON

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

409resource.in_useMás erőforrások még függnek ettől az erőforrástól.

Teendő: Ellenőrizze a függőségeket, és törlés előtt támogatott műveletekkel távolítsa el vagy módosítsa őket.
Újrapróbálási szabály: A függőségek rendezése után próbálkozzon újra.

JSON

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

409resource.state_conflictAz aktuális üzleti állapot nem teszi lehetővé a módosítást.

Teendő: Olvassa ki az aktuális állapotot, és válasszon érvényes üzleti állapotátmenetet.
Újrapróbálási szabály: Ne erőltesse automatikusan, és ne küldje el ismételten az ütköző módosítást.

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_conflictEgy másik írás módosította az erőforrást a verzió kiolvasása óta.

Teendő: Olvassa ki a legújabb állapotot, egyeztesse a módosítást, és adja meg az új expected_version értéket.
Újrapróbálási szabály: Az átdolgozott művelethez új idempotenciakulcsot használjon; ne írja felül az adatokat ellenőrzés nélkül.

JSON

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

413request.too_largeA kérés meghaladja a méretkorlátot.

Teendő: Csökkentse a küldött adatok méretét, vagy ossza a feladatot támogatott egyedi műveletekre.
Újrapróbálási szabály: Kisebb, érvényes műveleteket küldjön, mindegyiket saját idempotenciakulccsal.

JSON

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

415request.unsupported_media_typeA médiatípus vagy tartalomkódolás nem támogatott.

Teendő: JSON-íráshoz használjon Content-Type: application/json fejlécet és támogatott, tömörítetlen törzset.
Újrapróbálási szabály: A médiatípus vagy kódolás javítása után próbálkozzon újra.

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_failedEgy vagy több mező vagy paraméter érvénytelen.

Teendő: Vizsgálja meg az error.fields értékét, majd ellenőrizze a kötelező mezőket, a null megengedését, az azonosítókat és az engedélyezett értékeket.
Újrapróbálási szabály: Javított kérést küldjön; a módosított írás új logikai műveletnek számít.

JSON

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

429capacity.queue_fullA rövid API-várólista megtelt; a kérés végrehajtása nem kezdődött el.

Teendő: Állítsa sorba a kéréseket, és vegye figyelembe a válasz Retry-After fejlécét.
Újrapróbálási szabály: Várjon legalább Retry-After másodpercig, és adjon hozzá véletlenszerű időeltolást. Írás ismétlésekor tartsa meg az eredeti kulcsot és adatokat.

JSON

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

429capacity.wait_timeoutLejárt az API-várólistában töltött várakozási idő; a kérés végrehajtása nem kezdődött el.

Teendő: Állítsa sorba a kéréseket, és vegye figyelembe a válasz Retry-After fejlécét.
Újrapróbálási szabály: Várjon legalább Retry-After másodpercig, és adjon hozzá véletlenszerű időeltolást. Írás ismétlésekor tartsa meg az eredeti kulcsot és adatokat.

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.exceededA kérések gyakorisága meghaladja az érvényes korlátot.

Teendő: Állítsa sorba a kéréseket, és vegye figyelembe a válasz Retry-After fejlécét.
Újrapróbálási szabály: Várjon legalább Retry-After másodpercig, és adjon hozzá véletlenszerű időeltolást. Írás ismétlésekor tartsa meg az eredeti kulcsot és adatokat.

JSON

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

500internal.errorVáratlan szolgáltatáshiba történt.

Teendő: Jegyezze fel a kérés azonosítóját, és tartós hiba esetén forduljon az üzemeltetőhöz; hitelesítő adatot ne írjon a naplóba.
Újrapróbálási szabály: Korlátozott, növekvő várakozást használjon. Írásnál őrizze meg az eredeti idempotenciakulcsot és a változatlan adatokat.

JSON

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

502gateway.bad_responseAz átjáró nem kapott érvényes API-választ.

Teendő: Őrizze meg a kérés azonosítóját. A hibás válasz nem bizonyítja, hogy az írás nem történt meg.
Újrapróbálási szabály: Korlátozott, növekvő várakozást használjon; ugyanazt a logikai írást az eredeti Idempotency-Key értékkel és változatlan adatokkal ismételje.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAz API átmenetileg nem tudja kezelni a kérést.

Teendő: Ha van Retry-After fejléc, kövesse azt, és tartós kiesés esetén őrizze meg a kérés azonosítóját.
Újrapróbálási szabály: Korlátozott, növekvő várakozást és véletlenszerű időeltolást használjon; ugyanazon írás ismétlésekor őrizze meg a kulcsot és az adatokat.

JSON

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

504gateway.timeoutAz átjáró az API-ra várva időtúllépést észlelt.

Teendő: Őrizze meg a kérés azonosítóját, és az írás eredményét tekintse ismeretlennek.
Újrapróbálási szabály: Korlátozott, növekvő várakozást használjon; írás ismétlésekor tartsa meg az eredeti idempotenciakulcsot és a változatlan adatokat.

JSON

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