Hozzáférési hibák
Milyen hibával utasítanak el egy API tokent vagy OAuth-hozzáférést, és mi a teendő ilyenkor.
Ezen az oldalon
Az API tokennel (pltu_, plto_, pltd_) vagy OAuth access tokennel indított hívásokat a Poltura gateway-e
bírálja el a mögöttük álló jogosultságok alapján. Az elutasítás mindig ugyanazt a JSON bodyt adja vissza:
{
"error": "permission_denied",
"message": "this token does not allow orders.write on store:0199f3a2-7c41-7d2e-9b1a-3c5e8f0a1b2c",
"permission": "orders.write",
"resource": "store:0199f3a2-7c41-7d2e-9b1a-3c5e8f0a1b2c",
"documentation_url": "https://developers.poltura.com/api/errors#permission-denied"
}A permission és a resource mező akkor jelenik meg, ha az elutasítás egy adott bolt vagy szervezet egyetlen jogosultságára vonatkozik.
invalid-token
401. A hitelesítési adat ismeretlen, hibás formátumú, lejárt, visszavont, letiltott vagy kiszivárgott. A válasz
WWW-Authenticate: Bearer error="invalid_token", resource_metadata="…" headert tartalmaz; az OAuth-kliens ilyenkor
új engedélyezést indít, a token birtokosa pedig új tokent hoz létre vagy rotálja a meglévőt.
invalid-dpop-proof
401. A hitelesítési adat egy Poltura CLI-bejelentkezés, amely egy kulcshoz van kötve (DPoP),
és a kérés nem igazolta a kulcs birtoklását. A bizonyíték hiányzik, másik kulccsal van aláírva, másik
metódushoz, URL-hez vagy tokenhez készült, túl régi, vagy már felhasználták. A tokent Bearer sémával küldték el DPoP helyett,
vagy más hitelesítési adatot küldtek a DPoP sémával. A válasz WWW-Authenticate: DPoP error="invalid_dpop_proof" headert tartalmaz.
Használd a CLI-t azon a gépen, amelyen bejelentkeztél, vagy futtasd újra a poltura login parancsot.
use-dpop-nonce
401 (a token endpointon 400). A bizonyíték timestampje túlságosan eltér a szerverétől. A válasz
egy DPoP-Nonce headert tartalmaz: másold be ezt az értéket a bizonyíték nonce claimjébe, és küldd el újra a kérést. A CLI
ezt automatikusan megteszi.
insufficient-scope
403. Az OAuth-hozzáférésből hiányzik a jogosultság, és az újbóli bekérése segíthet. A challenge felsorolja
a hozzáférés által már birtokolt összes jogosultságot, kiegészítve a hiányzóval:
WWW-Authenticate: Bearer error="insufficient_scope", scope="orders.read products.read orders.write",
resource_metadata="…"Engedélyeztesd újra pontosan ezzel a scope értékkel. A jogosultsággal már rendelkező hozzáférés nem kap több ilyen challenge-et.
permission-denied
403. A token szabályzata nem engedélyezi a jogosultságot, a hozzáférés nem éri el ezt a boltot, vagy
a hozzáférést birtokló személy szerepköre már nem tartalmazza az adott jogosultságot. Ezen egy újabb hozzájárulás sem változtat.
not-delegable
403. A jogosultság soha nem használható hitelesítési adaton keresztül: második hitelesítési tényezőt igényel, kizárólag
tulajdonoshoz tartozik, magát a hozzáférést kezeli, vagy pénzmozgással jár. Végezd el az adminfelületen.
ip-not-allowed
403. A token használata megadott címekre van korlátozva, és ez a hívás nem azok egyikéről érkezett.
access-disabled
403. A szervezet kikapcsolta a külső appokat és AI-ügynököket, a bolt kikapcsolta az AI-ügynököket a
/mcp endpointon, a klienst letiltották, vagy a bolt, illetve a hozzáférés fel van függesztve.
approval-required
409. Egy AI-ügynök művelete emberi jóváhagyásra vár. Lásd: Jóváhagyás.
request-too-costly
400. Egyetlen hívás több mint 100 pontba kerülne, például egy lista túl nagy limit értékkel és sok include-dal. A hívás
nem futott le. Kérj kisebb oldalt vagy kevesebb include-ot. A költségeket lásd itt:
Hogyan működnek az AI-ügynökök a boltodban.
rate-limited
429. Kimerült a pontkeret ennél a hitelesítési adatnál, ennél a kliensnél az adott boltnál, vagy a bolt egészénél.
A body megnevezi a kimerült bucket elemet és a retryAfterMs értéket, a válasz pedig tartalmazza a Retry-After headert
másodpercben, valamint az X-Poltura-RateLimit-* headereket. A hívás nem érte el a boltot, így a megadott idő kivárása után
biztonságosan újraküldhető. MCP tool callon belül ugyanez az elutasítás egy rate_limited kódú eszközhiba.
unavailable
503. A Poltura éppen nem tudta elbírálni a hívást. Próbáld újra Retry-After másodperc elteltével; semmilyen művelet nem futott le.