Skip to main content
DomůBlogPrůvodciChyba autentizace Tracking API: 7 příčin odpovědí 401/403 a jak je opravit

Chyba autentizace Tracking API: 7 příčin odpovědí 401/403 a jak je opravit

17TRACK

Chyba ověřování Tracking API obvykle vzniká z jedné ze sedmi příčin: chybějící pověření, nesprávně naformátovaná hlavička ověřování, neplatný nebo odvolaný tajný klíč, nesoulad prostředí, nedostatečná oprávnění, vypršelý token nebo neplatný podpis, případně bezpečnostní pravidlo blokující požadavek. Chcete-li opravit odpověď 401 nebo 403, nejprve zjistěte, který systém ji vrátil, a poté porovnejte požadavek s požadavky poskytovatele na ověřování. Opakované pokusy se stejnými pověřeními jen zřídka vyřeší příčinu problému.

7 příčin chyb ověřování Tracking API a odpovědí 401 a 403

Tato příručka je určena vývojářům a integračním týmům, které připojují sledování zásilek k ecommerce platformě, systému pro správu objednávek, skladové aplikaci nebo internímu dashboardu. Začněte jedním neúspěšným požadavkem, místo abyste měnili pověření v celé integraci.

Nejprve rozlišujte 401 a 403

Definice HTTP představují výchozí bod, nikoli úplnou diagnózu. 401 Unauthorized znamená, že požadavku chybí platná ověřovací pověření pro cílový prostředek. 403 Forbidden znamená, že server požadavku porozuměl, ale odmítá jej splnit. Odpověď 403 nemusí nutně dokazovat, že ověření proběhlo úspěšně: brána nebo bezpečnostní služba může požadavek odmítnout dříve, než aplikace vyhodnotí jeho pověření.

Podle RFC 9110 musí server generující odpověď 401 zahrnout výzvu WWW-Authenticate. Pokud je tato hlavička přítomna, zkontrolujte ji, ale přečtěte si také tělo odpovědi a dokumentaci poskytovatele k chybám. Jednotlivé implementace chyby ne vždy zpřístupňují stejným způsobem.

Co pozorujeteCo nejprve prověřit
401 se zprávou o chybějícím nebo neplatném pověřeníVložení pověření, formát hlavičky a platnost pověření
403 se zprávou o nedostatečném oprávněníObory oprávnění, přístup k účtu, tenant a vlastnictví prostředku
403 s HTML bezpečnostní stránkouBránu, proxy, firewall nebo zásady přístupu
Úspěch HTTP s chybou uvnitř JSONPole chyb na úrovni aplikace poskytovatele

Ve svých protokolech udržujte stav přenosu a stav aplikace odděleně. Pole JSON pojmenované code není automaticky stav HTTP a úspěšná komunikace HTTP nemusí znamenat, že požadovaná operace sledování proběhla úspěšně.

Pořiďte bezpečný diagnostický záznam

Než cokoli změníte, zaznamenejte časové razítko UTC, metodu HTTP, název hostitele, cestu, stav odpovědi, chybovou zprávu poskytovatele, ID požadavku a prostředí nasazení. Poznamenejte si, zda odpověď přišla od poskytovatele sledování, vašeho backendu nebo prostředníka.

Zaznamenejte názvy ověřovacích hlaviček a informaci, zda jsou jejich hodnoty přítomné, ale nikdy neprotokolujte úplné klíče API, bearer tokeny, obnovovací tokeny ani podpisové tajné klíče. Neexportujte neanonymizované trasování požadavků. Čísla zásilek a podrobnosti o zásilkách mohou podle pravidel vaší organizace pro nakládání s daty také vyžadovat anonymizaci.

K reprodukci problému použijte operaci s nízkým dopadem popsanou v dokumentaci poskytovatele. Opakovaně neregistrujte zásilky, nevytvářejte odběry ani neměňte nastavení webhooků pouze kvůli testování ověřování.

7 příčin odpovědí 401/403 Tracking API

1. Pověření se k API nikdy nedostane

Tajný klíč může existovat v konzoli nasazení, aniž by byl dostupný běžící aplikaci. Mezi běžná místa selhání patří chybějící proměnná prostředí, nesprávný odkaz na tajný klíč, pracovní proces, který nebyl po změně konfigurace restartován, nebo tvůrce požadavku, který vynechává prázdné hodnoty.

Proxy může také odstranit ověřovací hlavičku. Pozornost věnujte přesměrováním, protože klient HTTP nemusí předat citlivé hlavičky jinému hostiteli.

  • Kontrola: Zkontrolujte požadavek v posledním důvěryhodném výstupním bodě. Ověřte, že požadovaná hlavička existuje a obsahuje neprázdnou hodnotu.
  • Oprava: Opravte mapování tajného klíče nebo sestavení požadavku a v případě potřeby znovu načtěte dotčený proces.
  • Ověření: Proveďte stejnou operaci prostřednictvím nasazené aplikace, nejen z notebooku vývojáře.

Pokud lokální požadavky fungují, ale úlohy na pozadí selhávají, nejprve porovnejte jejich konfiguraci běhového prostředí. Aplikace a její pracovní procesy mohou získávat tajné klíče různými mechanismy.

2. Formát ověřování je nesprávný

Tracking API nepřijímají všechna stejné schéma ověřování. Poskytovatel může vyžadovat vyhrazenou hlavičku API klíče, bearer token OAuth nebo podepsaný požadavek. Vložení platného klíče do Authorization: Bearer nepomůže, pokud koncový bod očekává jinou hlavičku.

Mezi další chyby patří zkopírování uvozovek do tajného klíče, přidání předpony, kterou poskytovatel nevyžaduje, odeslání duplicitních ověřovacích hlaviček nebo použití konfiguračního pole SDK určeného pro jinou metodu ověřování.

  • Kontrola: Porovnejte skutečný požadavek s oficiálním příkladem pro přesný koncový bod a verzi API.
  • Oprava: Použijte zdokumentovaný název hlavičky, formát hodnoty a schéma ověřování. Nepřesouvejte tajný klíč do URL jako náhradní řešení.
  • Ověření: Porovnejte minimální požadavek s požadavkem vytvořeným SDK a přitom anonymizujte pověření.

Názvy polí hlaviček HTTP nerozlišují velká a malá písmena. Samotná změna velikosti písmen proto obvykle není řešením. Zaměřte se na správné pole, hodnotu a cestu přenosu.

3. Klíč je nesprávný, odvolaný nebo již není konzistentně nasazen

Zkopírovaný klíč může být neúplný, patřit jinému účtu nebo mohl být během bezpečnostní změny odvolán. Rotace pověření může také způsobovat občasná selhání: některé instance aplikace používají náhradní tajný klíč, zatímco jiné stále používají starý.

Nepředpokládejte, že každý klíč API automaticky expiruje. Pravidla expirace a rotace závisí na poskytovateli a typu pověření.

  • Kontrola: Ověřte stav pověření v konzoli autorizovaného účtu a porovnejte nasazenou verzi tajného klíče napříč aplikacemi, pracovními procesy a plánovanými úlohami.
  • Oprava: Pomocí procesu správy tajných klíčů nasaďte platné pověření. Pokud máte podezření na únik, postupujte podle incidentního procesu a kompromitované pověření odvolejte.
  • Ověření: Po nasazení zkontrolujte každou dotčenou cestu provedení. Jediný úspěšný požadavek nedokazuje, že všechny instance byly aktualizovány.

Pokud je to podporováno, používejte k rozlišení nasazení necitlivý identifikátor pověření nebo verzi ve správci tajných klíčů. Nikdy nežádejte zákazníka ani kolegu, aby vložil celý klíč do tiketu podpory.

4. Pověření a koncový bod patří do různých prostředí

Některé služby oddělují produkční a testovací pověření, regionální koncové body, účty nebo tenanty. Platné pověření může selhat, pokud je odesláno na nesprávného hostitele nebo do nesprávného kontextu účtu. Tato kontrola platí pouze tam, kde poskytovatel tyto rozdíly dokumentuje.

Další možností je zastaralá základní URL. Integrace může používat starý koncový bod, zatímco její konfigurace ověřování již byla aktualizována pro novější API.

  • Kontrola: Zkontrolujte celý cíl: schéma, název hostitele, verzi API, cestu a případný požadovaný identifikátor účtu nebo tenanta.
  • Oprava: Spárujte pověření s určeným prostředím a koncovým bodem. Udržujte URL a konfiguraci tajných klíčů jednotlivých prostředí pohromadě.
  • Ověření: Potvrďte vyřešený cíl v běžícím nasazení a ověřte, zda klient sleduje přesměrování.

Netestujte seznam uhádnutých hostitelů se skutečným pověřením. Používejte pouze koncové body zdokumentované poskytovatelem.

5. Ověření proběhne úspěšně, ale oprávnění jsou nedostatečná

Pověření může identifikovat volajícího, aniž by jej opravňovalo k požadované operaci. Čtení událostí zásilek, registrace sledovacích čísel, změna odběrů a správa účtu mohou vyžadovat různá přístupová práva.

Důležité je také vlastnictví prostředku. Zásilka viditelná v jednom pracovním prostoru nemusí být přístupná prostřednictvím pověření spojeného s jiným. Některé systémy záměrně omezují podrobnosti chyb, takže samotná odpověď 403 nemůže potvrdit, zda prostředek existuje.

  • Kontrola: Prověřte obory oprávnění, role, členství v účtu, vlastnictví prostředku a požadavky na přístup pro konkrétní koncový bod.
  • Oprava: Udělte integraci pouze požadované oprávnění nebo použijte správný autorizovaný účet.
  • Ověření: Otestujte neúspěšnou operaci proti prostředku, o němž je známo, že jej účet spravuje.

U bearer tokenů OAuth rozlišuje RFC 6750 mezi invalid_token a insufficient_scope. Pokud poskytovatel tuto konvenci dodržuje, první hodnota ukazuje na platnost tokenu, zatímco druhá na autorizaci. Nepředpokládejte, že každé Tracking API používá OAuth nebo tato chybová pole.

6. Token vypršel nebo je podpis požadavku neplatný

Časově citlivé ověřování přináší další způsoby selhání nad rámec nesprávného statického klíče. Přístupový token OAuth může vypršet. Podepsaný požadavek může být odmítnut, protože jeho časové razítko leží mimo povolené okno nebo protože server vypočítá jiný podpis.

Neshody podpisů mohou vzniknout podepsáním jednoho těla požadavku a odesláním jiného, odlišným kódováním cesty, změnou parametrů dotazu nebo použitím nesprávného podpisového tajného klíče. Tyto kontroly platí pouze pro API, která dokumentují podepsané požadavky.

  • Kontrola: Zkontrolujte expiraci tokenu a výsledky obnovení. U podpisů porovnejte zdokumentovaný kanonický požadavek s přesně odeslanými bajty a poli.
  • Oprava: Obnovte nebo získejte tokeny podporovaným postupem, synchronizujte systémový čas a podpisy vytvářejte až po dokončení všech podepisovaných částí požadavku.
  • Ověření: Testujte také přes další hranici obnovení tokenu, nejen bezprostředně po získání nového tokenu.

V systémech s více pracovními procesy koordinujte obnovování tokenů, aby pracovní procesy opakovaně nepřepisovaly použitelná pověření nebo nespouštěly souběžná obnovení. Obnovovací tokeny chraňte odděleně od běžných protokolů požadavků.

7. Brána, firewall nebo síťová zásada požadavek blokuje

Odpověď 403 může pocházet mimo aplikaci pro sledování. Mezi možné příčiny patří nesoulad seznamu povolených IP adres, zásada odchozí proxy, pravidlo webového aplikačního firewallu nebo přístupová brána vyžadující vlastní autorizaci.

HTML stránka odmítnutí, neznámá hlavička odpovědi nebo ID požadavku specifické pro bránu mohou pomoci určit vrstvu, která požadavek odmítla. Jde o vodítka, nikoli důkaz; potvrďte je v protokolech brány nebo u týmu podpory poskytovatele.

  • Kontrola: Porovnejte veřejnou výstupní IP adresu a síťovou trasu neúspěšného nasazení se známým funkčním prostředím.
  • Oprava: Prostřednictvím odpovědného infrastrukturního týmu opravte příslušný seznam povolených adres, konfiguraci proxy nebo úzce vymezené bezpečnostní pravidlo.
  • Ověření: Po změně zásady požadavek zopakujte z původního běhového prostředí.

Nevypínejte ověřování certifikátů TLS ani obecně neobcházejte bezpečnostní kontroly. Selhání CORS v prohlížeči také vyžaduje samostatnou diagnostiku: zjistěte, zda odmítnutým požadavkem je předběžný požadavek OPTIONS, nebo skutečné volání API. Dlouhodobá tajemství Tracking API nesmí být vystavena v kódu prohlížeče.

K izolaci chyby použijte minimální požadavek

Omezte neúspěšné volání na zdokumentovaný koncový bod, metodu, požadované ověření a nejmenší platné tělo. Následující příklad je obecná diagnostická šablona, nikoli funkční požadavek specifický pro poskytovatele:

curl --include \
  --request "$DOCUMENTED_METHOD" \
  --url "$DOCUMENTED_ENDPOINT" \
  --header "$DOCUMENTED_AUTH_HEADER: $DOCUMENTED_AUTH_VALUE"

Pokud to operace vyžaduje, přidejte požadovaný typ obsahu a tělo. Používejte tento postup pouze v kontrolovaném prostředí: argumenty příkazů, záznamy terminálu a diagnostické nástroje mohou odhalit tajné klíče. Vyhněte se podrobnému trasování, pokud nedokážete jeho výstup chránit a anonymizovat.

Pokud minimální požadavek uspěje, ale aplikace selže, zkontrolujte konfiguraci SDK, sestavení hlaviček, přesměrování, chování proxy a tajné klíče běhového prostředí. Pokud selžou oba požadavky, prověřte platnost pověření, výběr koncového bodu, oprávnění a síťové zásady. Měňte vždy jednu proměnnou, aby výsledek určil příčinu.

Použití kontrol v integraci 17TRACK

U integrace 17TRACK Tracking API začněte u oficiální dokumentace API a dodržte pokyny k ověřování a formát požadavku pro volanou operaci. Nenahrazujte vzor ověřování převzatý z nesouvisejícího API a nepředpokládejte, že přístup ke spotřebitelské stránce sledování potvrzuje autorizaci API.

Porovnejte zdokumentovaný požadavek s požadavkem odcházejícím z vašeho serveru a poté zkontrolujte odpověď HTTP i zdokumentovaná pole odpovědi. Pokud je nutná eskalace, odešlete anonymizovaný příklad, časové razítko, koncový bod, podrobnosti odpovědi a pokud možno identifikátor požadavku. Tajný klíč API do hlášení nevkládejte.

Přestaňte se slepými opakovanými pokusy a potvrďte obnovení

Selhání ověřování by mělo spustit diagnostiku, nikoli neomezenou smyčku opakování. U výslovně vypršelého tokenu může být vhodné řízené obnovení následované omezeným opakováním. U chybějících oprávnění, odvolaných pověření nebo zablokované síťové cesty opakované pokusy konfiguraci neopraví.

Před opakováním operace zápisu zkontrolujte chování poskytovatele při idempotenci nebo zpracování duplicit. To je důležité, když prostředník způsobí nejistotu ohledně původního výsledku.

Obnovení je dokončeno, když zamýšlená operace uspěje z původního nasazení, všechny relevantní pracovní procesy používají správnou konfiguraci a monitorování neukazuje pokračující selhání ověřování. Stav HTTP a chyby na úrovni aplikace sledujte odděleně a používejte upozornění, která identifikují dotčený koncový bod a prostředí, aniž by odhalovala pověření.

Časté dotazy

Proč požadavek funguje lokálně, ale v produkci selhává?

Porovnejte verze tajných klíčů, základní URL, odchozí proxy, výstupní IP adresy, systémové hodiny a konfiguraci běhového prostředí. Lokální úspěch potvrzuje, že funguje jedna cesta požadavku; nepotvrzuje, že produkce odesílá stejný požadavek nebo má stejná oprávnění.

Mám okamžitě vygenerovat nový klíč API?

Ne, pokud současné pověření není neplatné, odvolané nebo potenciálně odhalené. Nejprve ověřte, zda se dostane ke správnému koncovému bodu v požadovaném formátu. Zbytečná rotace může způsobit selhání v dalších službách, které stále závisí na existujícím klíči.

Může nesprávné sledovací číslo způsobit 401 nebo 403?

Neplatné sledovací číslo je obvykle otázkou validace nebo prostředku, nikoli důkazem neplatného ověření. Přístup k zásilce však může být omezen vlastnictvím účtu. Použijte zdokumentované podrobnosti chyb poskytovatele a nediagnostikujte problém pouze podle čísla.

Znamená 403, že moje předplatné API vypršelo?

Ne. Omezení předplatného nebo nároku je pouze jednou z možností, pokud je poskytovatel dokumentuje nebo vrací konkrétní zprávu. Odmítnutí mohou způsobit také oprávnění, kontext účtu a bezpečnostní zásady. Nevyvozujte z pouhého stavu HTTP problém s fakturací.

Co mám zahrnout do požadavku na podporu?

Uveďte časové razítko UTC, metodu, koncový bod, prostředí, stav HTTP, anonymizované tělo odpovědi, ID požadavku a informaci, zda se problém opakuje u minimálního požadavku. Popište nedávná nasazení nebo změny pověření. Vynechte tajné klíče a anonymizujte data zásilek, která nejsou pro diagnostiku potřebná.

Zdroje