Skip to main content
EtusivuBlogiOppaatTracking API -todennusvirhe: 7 syytä 401/403-vastauksiin ja niiden korjaaminen

Tracking API -todennusvirhe: 7 syytä 401/403-vastauksiin ja niiden korjaaminen

17TRACK

Seuranta-API:n todennusvirhe johtuu yleensä yhdestä seitsemästä syystä: puuttuvasta tunnistetiedosta, väärin muotoillusta todennusotsakkeesta, virheellisestä tai perutusta salaisuudesta, ympäristöjen yhteensopimattomuudesta, riittämättömistä käyttöoikeuksista, vanhentuneesta tunnuksesta tai virheellisestä allekirjoituksesta taikka pyynnön estävästä suojaussäännöstä. Korjataksesi 401- tai 403-vastauksen selvitä ensin, mikä järjestelmä palautti sen, ja tarkista sitten pyyntö palveluntarjoajan todennusvaatimuksia vasten. Muuttumattomilla tunnistetiedoilla tehdyt toistuvat uudelleenyritykset ratkaisevat harvoin taustalla olevan ongelman.

Seuranta-API:n todennusvirhe: 7 syytä 401- ja 403-vastauksille

Tämä opas on tarkoitettu kehittäjille ja integraatiotiimeille, jotka yhdistävät lähetysten seurannan verkkokauppa-alustaan, tilaustenhallintajärjestelmään, varastosovellukseen tai sisäiseen hallintapaneeliin. Aloita yhdestä epäonnistuvasta pyynnöstä sen sijaan, että vaihtaisit tunnistetiedot koko integraatiossa.

Erota ensin 401- ja 403-virheet

HTTP-määritelmät tarjoavat lähtökohdan, eivät täydellistä diagnoosia. 401 Unauthorized tarkoittaa, että pyynnöstä puuttuvat kohderesurssin voimassa olevat todennustiedot. 403 Forbidden tarkoittaa, että palvelin ymmärsi pyynnön mutta kieltäytyy täyttämästä sitä. 403 ei välttämättä todista todennuksen onnistuneen: yhdyskäytävä tai suojauspalvelu voi hylätä pyynnön ennen kuin sovellus arvioi sen tunnistetiedot.

RFC 9110:n mukaan 401-vastauksen tuottavan palvelimen on sisällytettävä WWW-Authenticate-haaste. Tarkista tämä otsake, jos se on saatavilla, mutta lue myös vastausrungon sisältö ja palveluntarjoajan virhedokumentaatio. Toteutukset eivät aina ilmoita virheistä samalla tavalla.

HavaintoMitä tutkitaan ensin
401 ja puuttuvaa tai virheellistä tunnistetietoa koskeva viestiTunnistetietojen välitys, otsakkeen muoto ja tunnistetietojen voimassaolo
403 ja riittämättömiä käyttöoikeuksia koskeva viestiLaajuudet, tilin käyttöoikeus, vuokraaja ja resurssin omistajuus
403 ja HTML-muotoinen suojaussivuYhdyskäytävä, välityspalvelin, palomuuri tai käyttöoikeuskäytäntö
HTTP-onnistuminen ja JSON:n sisäinen virhePalveluntarjoajan sovellustason virhekentät

Pidä siirtotason tila ja sovellustason tila erillään lokeissa. code-niminen JSON-kenttä ei automaattisesti ole HTTP-tila, eikä onnistunut HTTP-vaihto välttämättä tarkoita, että pyydetty seurantatoiminto onnistui.

Tallenna turvallinen diagnostiikkatietue

Kirjaa ennen muutosten tekemistä UTC-aikaleima, HTTP-metodi, isäntänimi, polku, vastaustila, palveluntarjoajan virheviesti, pyynnön tunnus ja käyttöönottoympäristö. Merkitse, tuliko vastaus seurantapalveluntarjoajalta, omasta taustajärjestelmästäsi vai välittäjältä.

Kirjaa todennusotsakkeiden nimet ja se, ovatko arvot mukana, mutta älä koskaan kirjaa kokonaisia API-avaimia, bearer-tunnuksia, päivitystunnuksia tai allekirjoitussalaisuuksia. Vältä peittämättömien pyyntöjälkien vientiä. Seurantanumerot ja lähetystiedot voivat myös edellyttää peittämistä organisaatiosi tietojenkäsittelysääntöjen mukaisesti.

Käytä palveluntarjoajan dokumentoimaa, vähän vaikutuksia aiheuttavaa toimintoa ongelman toistamiseen. Älä rekisteröi lähetyksiä toistuvasti, luo tilauksia tai muuta webhook-asetuksia vain todennuksen testaamiseksi.

Seuranta-API:n 401/403-vastausten 7 syytä

1. Tunnistetieto ei koskaan saavuta API:a

Salaisuus voi olla olemassa käyttöönottokonsolissa ilman, että käynnissä oleva sovellus pääsee siihen käsiksi. Yleisiä vikakohtia ovat puuttuva ympäristömuuttuja, virheellinen salaisuusviittaus, määritysmuutoksen jälkeen käynnistämättä jäänyt työntekijä tai pyyntömuodostin, joka jättää tyhjät arvot pois.

Välityspalvelin voi myös poistaa todennusotsakkeen. Uudelleenohjaukset vaativat huomiota, koska HTTP-asiakas ei ehkä välitä arkaluonteisia otsakkeita eri isäntään.

  • Tarkista: Tarkasta pyyntö viimeisessä luotetussa ulospäin suuntautuvassa pisteessä. Varmista, että vaadittu otsake on olemassa ja sisältää ei-tyhjän arvon.
  • Korjaa: Korjaa salaisuuden määritys tai pyynnön muodostus ja lataa tarvittaessa kyseinen prosessi uudelleen.
  • Vahvista: Suorita sama toiminto käyttöön otetun sovelluksen kautta, ei vain kehittäjän kannettavalta.

Jos paikalliset pyynnöt toimivat mutta taustatyöt epäonnistuvat, vertaa ensin niiden ajonaikaisia määrityksiä. Sovellus ja sen työtekijät voivat saada salaisuudet eri mekanismeilla.

2. Todennusmuoto on väärä

Kaikki seuranta-API:t eivät hyväksy samaa todennusmenetelmää. Palveluntarjoaja voi vaatia erillisen API-avainotsakkeen, OAuth bearer -tunnuksen tai allekirjoitetun pyynnön. Voimassa olevan avaimen lisääminen otsakkeeseen Authorization: Bearer ei auta, jos päätepiste odottaa eri otsaketta.

Muita virheitä ovat lainausmerkkien kopioiminen salaisuuteen, palveluntarjoajan vaatimattoman etuliitteen lisääminen, päällekkäisten todennusotsakkeiden lähettäminen tai SDK-määrityskentän käyttäminen, joka koskee eri todennusmenetelmää.

  • Tarkista: Vertaa todellista pyyntöä viralliseen esimerkkiin juuri kyseisestä päätepisteestä ja API-versiosta.
  • Korjaa: Käytä dokumentoitua otsakkeen nimeä, arvomuotoa ja todennusmenetelmää. Älä siirrä salaisuutta URL-osoitteeseen kiertotienä.
  • Vahvista: Vertaa minimaalista pyyntöä SDK:n muodostamaan pyyntöön pitäen tunnistetiedot peitettyinä.

HTTP-otsakekenttien nimet eivät ole kirjainkoon suhteen merkitseviä HTTP-semantiiikassa. Pelkkä kirjainkoon muuttaminen ei siksi yleensä korjaa ongelmaa. Keskity oikeaan kenttään, arvoon ja välitysreittiin.

3. Avain on virheellinen, peruttu tai sitä ei ole otettu käyttöön yhdenmukaisesti

Kopioitu avain voi olla puutteellinen, kuulua toiselle tilille tai se on voitu perua tietoturvamuutoksen aikana. Tunnistetietojen kierrätys voi myös aiheuttaa ajoittaisia virheitä: jotkin sovellusinstanssit käyttävät korvaavaa salaisuutta, kun taas toiset käyttävät edelleen vanhaa.

Älä oleta, että jokainen API-avain vanhenee automaattisesti. Vanhentumis- ja kierrätyssäännöt riippuvat palveluntarjoajasta ja tunnistetietojen tyypistä.

  • Tarkista: Vahvista tunnistetietojen tila valtuutetun tilin konsolissa ja vertaa käyttöön otettua salaisuusversiota sovelluksissa, työtekijöissä ja ajoitetuissa tehtävissä.
  • Korjaa: Ota voimassa oleva tunnistetieto käyttöön salaisuudenhallintaprosessisi kautta. Jos paljastumista epäillään, noudata poikkeamamenettelyäsi ja peru vaarantunut tunnistetieto.
  • Vahvista: Tarkista jokainen vaikuttava suorituspolku käyttöönoton jälkeen. Yksi onnistunut pyyntö ei todista, että kaikki instanssit on päivitetty.

Jos mahdollista, käytä ei-salaiseksi tarkoitettua tunnistetietotunnistetta tai salaisuudenhallinnan versiota käyttöönottoversioiden erottamiseen. Älä koskaan pyydä asiakasta tai työtoveria liittämään kokonaista avainta tukipyyntöön.

4. Tunnistetieto ja päätepiste kuuluvat eri ympäristöihin

Jotkin palvelut erottavat tuotanto- ja testiympäristön tunnistetiedot, alueelliset päätepisteet, tilit tai vuokraajat. Voimassa oleva tunnistetieto voi epäonnistua, kun se lähetetään väärälle isännälle tai tilikontekstille. Tarkistus koskee vain palveluntarjoajan dokumentoimia erotteluja.

Toinen mahdollisuus on vanhentunut perus-URL. Integraatio voi käyttää vanhaa päätepistettä, vaikka sen todennusmääritys on jo päivitetty uudempaa API:a varten.

  • Tarkista: Tarkista koko kohde: skeema, isäntänimi, API-versio, polku sekä mahdollinen vaadittu tili- tai vuokraajatunniste.
  • Korjaa: Yhdistä tunnistetieto sille tarkoitettuun ympäristöön ja päätepisteeseen. Säilytä kunkin ympäristön URL- ja salaisuusmääritykset yhdessä.
  • Vahvista: Varmista ratkaistu kohde käynnissä olevassa käyttöönotossa ja tarkista, seuraako asiakas uudelleenohjauksia.

Vältä arvaamalla koottujen isäntäluetteloiden testaamista oikealla tunnistetiedolla. Käytä vain palveluntarjoajan dokumentoimia päätepisteitä.

5. Todennus onnistuu, mutta käyttöoikeus ei riitä

Tunnistetieto voi tunnistaa kutsujan ilman, että se valtuuttaa pyydetyn toiminnon. Lähetystapahtumien lukeminen, seurantanumeroiden rekisteröinti, tilausten muuttaminen ja tilin hallinta voivat edellyttää eri käyttöoikeuksia.

Myös resurssin omistajuudella on merkitystä. Yhdessä työtilassa näkyvään lähetykseen ei ehkä pääse toiselle liitetyn tunnistetiedon kautta. Jotkin järjestelmät rajoittavat tarkoituksella virheen yksityiskohtia, joten pelkkä 403 ei voi osoittaa resurssin olemassaoloa.

  • Tarkista: Tarkasta laajuudet, roolit, tilin jäsenyys, resurssin omistajuus ja päätepistekohtaiset käyttöoikeusvaatimukset.
  • Korjaa: Myönnä integraatiolle vain tarvittava käyttöoikeus tai käytä oikeaa valtuutettua tiliä.
  • Vahvista: Testaa epäonnistuva toiminto resurssilla, jota tilin tiedetään hallitsevan.

OAuth bearer -tunnuksille RFC 6750 erottaa invalid_token- ja insufficient_scope-virheet. Jos palveluntarjoaja noudattaa tätä käytäntöä, ensimmäinen viittaa tunnuksen voimassaoloon ja jälkimmäinen valtuutukseen. Älä oleta, että jokainen seuranta-API käyttää OAuthia tai näitä virhekenttiä.

6. Tunnus on vanhentunut tai pyynnön allekirjoitus on virheellinen

Aikaherkkä todennus lisää vikatiloja virheellisen staattisen avaimen lisäksi. OAuth-käyttötunnus voi vanhentua. Allekirjoitettu pyyntö voidaan hylätä, koska sen aikaleima on hyväksytyn ikkunan ulkopuolella tai palvelin laskee erilaisen allekirjoituksen.

Allekirjoituserot voivat johtua yhden pyynnön rungon allekirjoittamisesta ja toisen lähettämisestä, polun erilaisesta koodauksesta, kyselyparametrien muuttamisesta tai väärän allekirjoitussalaisuuden käytöstä. Nämä tarkistukset koskevat vain API:ita, jotka dokumentoivat allekirjoitetut pyynnöt.

  • Tarkista: Tutki tunnuksen vanheneminen ja päivitystulokset. Vertaa allekirjoitusten osalta dokumentoitua kanonista pyyntöä lähetettyihin täsmällisiin tavuihin ja kenttiin.
  • Korjaa: Päivitä tai hanki tunnukset tuetun työnkulun kautta, synkronoi järjestelmän aika ja luo allekirjoitukset, kun allekirjoitettavan pyynnön osat on viimeistelty.
  • Vahvista: Testaa seuraavan tunnuksen päivityskohdan yli, ei vain heti uuden tunnuksen hankkimisen jälkeen.

Usean työntekijän järjestelmissä koordinoi tunnusten päivitykset, jotta työntekijät eivät toistuvasti korvaa käyttökelpoisia tunnistetietoja tai käynnistä kilpailevia päivityksiä. Suojaa päivitystunnukset erillään tavallisista pyyntölokeista.

7. Yhdyskäytävä, palomuuri tai verkkokäytäntö estää pyynnön

403 voi syntyä seurantajärjestelmän ulkopuolella. Mahdollisia syitä ovat IP-sallittujen osoitteiden ristiriita, lähtevän välityspalvelimen käytäntö, web-sovelluksen palomuurisääntö tai omaa valtuutusta vaativa käyttöoikeusyhdyskäytävä.

HTML-muotoinen estämissivu, tuntematon vastausotsake tai yhdyskäytäväkohtainen pyynnön tunnus voi auttaa tunnistamaan hylkäävän kerroksen. Nämä ovat vihjeitä, eivät todisteita; vahvista ne yhdyskäytävän lokeista tai palveluntarjoajan tuelta.

  • Tarkista: Vertaa epäonnistuvan käyttöönoton julkista lähtevää IP-osoitetta ja verkkoreittiä tunnetusti toimivaan ympäristöön.
  • Korjaa: Korjaa vastuullisen infrastruktuuritiimin avulla asiaankuuluva sallittujen osoitteiden luettelo, välityspalvelimen määritys tai tarkasti rajattu suojaussääntö.
  • Vahvista: Toista pyyntö alkuperäisestä ajonaikaisesta ympäristöstä käytäntömuutoksen jälkeen.

Älä poista TLS-varmenteiden tarkistusta käytöstä tai ohita suojausvalvontaa laajasti. Selaimen CORS-virheet vaativat erillisen diagnoosin: tarkista, onko hylätty pyyntö esikutsupyyntö OPTIONS vai varsinainen API-kutsu. Pitkäikäisiä seuranta-API:n salaisuuksia ei pidä paljastaa selainkoodissa.

Käytä minimaalista pyyntöä vian eristämiseen

Rajaa epäonnistuva kutsu dokumentoituun päätepisteeseen, metodiin, vaadittuun todennukseen ja pienimpään kelvolliseen hyötykuormaan. Seuraava on yleinen diagnostiikkamalli, ei tietyn palveluntarjoajan toimiva pyyntö:

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

Lisää vaadittu sisältötyyppi ja runko, jos toiminto niitä tarvitsee. Käytä tätä vain valvotussa ympäristössä: komentoriviargumentit, päätetallenteet ja diagnostiikkatyökalut voivat paljastaa salaisuuksia. Vältä yksityiskohtaisia jäljityksiä, ellet voi suojata ja peittää niiden tulostetta.

Jos minimaalinen pyyntö onnistuu mutta sovellus epäonnistuu, tarkasta SDK-määritys, otsakkeen muodostus, uudelleenohjaukset, välityspalvelimen toiminta ja ajonaikaiset salaisuudet. Jos molemmat epäonnistuvat, tutki tunnistetietojen voimassaolo, päätepisteen valinta, käyttöoikeudet ja verkkokäytäntö. Muuta yhtä muuttujaa kerrallaan, jotta tulos tunnistaa syyn.

Tarkistusten soveltaminen 17TRACK-integraatioon

Kun kyseessä on 17TRACK Tracking API -integraatio, aloita virallisesta API-dokumentaatiosta ja sovita kutsumasi toiminnon todennusohjeet ja pyyntömuoto niihin. Älä korvaa niitä toisesta, asiaan liittymättömästä API:sta kopioidulla todennusmallilla tai oleta, että kuluttajille tarkoitetun seurantatietosivun käyttöoikeus vahvistaa API-valtuutuksen.

Vertaa dokumentoitua pyyntöä palvelimeltasi lähtevään pyyntöön ja tarkasta sitten sekä HTTP-vastaus että dokumentoidut vastauskentät. Jos eskalointi on tarpeen, lähetä peitetty esimerkki, aikaleima, päätepiste, vastaustiedot ja pyynnön tunniste, jos saatavilla. Pidä API-salaisuus poissa raportista.

Lopeta sokkouudelleenyritykset ja vahvista palautuminen

Todennusvirheiden tulisi käynnistää diagnoosi rajoittamattoman uudelleenyrityssilmukan sijaan. Nimenomaisesti vanhentuneen tunnuksen tapauksessa hallittu päivitys ja rajattu uudelleenyritys voi olla sopiva. Puuttuvien käyttöoikeuksien, peruttujen tunnistetietojen tai estetyn verkkoreitin tapauksessa uudelleenyritykset eivät korjaa määritystä.

Tarkista ennen kirjoitustoiminnon toistamista palveluntarjoajan idempotenssi- tai kaksoiskäsittelykäytäntö. Tämä on tärkeää, kun välittäjä tekee alkuperäisen tuloksen epävarmaksi.

Palautuminen on valmis, kun tarkoitettu toiminto onnistuu alkuperäisestä käyttöönotosta, kaikki asiaankuuluvat työntekijät käyttävät oikeaa määritystä ja valvonta ei osoita jatkuvia todennusvirheitä. Seuraa HTTP-tilaa ja sovellustason virheitä erikseen ja käytä hälytyksiä, jotka tunnistavat vaikuttaneen päätepisteen ja ympäristön paljastamatta tunnistetietoja.

UKK

Miksi pyyntö toimii paikallisesti mutta epäonnistuu tuotannossa?

Vertaa salaisuusversioita, perus-URL-osoitteita, lähteviä välityspalvelimia, lähteviä IP-osoitteita, järjestelmän kelloja ja ajonaikaisia määrityksiä. Paikallinen onnistuminen osoittaa, että yksi pyyntöpolku toimii; se ei osoita, että tuotanto lähettää saman pyynnön tai että sillä on samat käyttöoikeudet.

Pitäisikö minun luoda uusi API-avain heti?

Ei, ellei nykyinen tunnistetieto ole virheellinen, peruttu tai mahdollisesti paljastunut. Tarkista ensin, saapuuko se oikeaan päätepisteeseen vaaditussa muodossa. Tarpeeton kierrätys voi aiheuttaa virheitä muissa palveluissa, jotka yhä riippuvat nykyisestä avaimesta.

Voiko väärä seurantanumero aiheuttaa 401- tai 403-virheen?

Virheellinen seurantanumero on yleensä validointi- tai resurssitason ongelma, ei todiste virheellisestä todennuksesta. Lähetyksen käyttöoikeutta voidaan kuitenkin rajoittaa tilin omistajuuden perusteella. Käytä palveluntarjoajan dokumentoituja virhetietoja sen sijaan, että tekisit diagnoosin pelkän numeron perusteella.

Tarkoittaako 403, että API-tilaukseni on vanhentunut?

Ei. Tilaus- tai käyttöoikeusrajoitukset ovat yksi mahdollisuus vain, jos palveluntarjoaja dokumentoi ne tai palauttaa tietyn viestin. Myös käyttöoikeudet, tilikonteksti ja suojauskäytännöt voivat aiheuttaa hylkäyksen. Älä päättele laskutusongelmaa pelkän HTTP-tilan perusteella.

Mitä tukipyyntöön pitäisi sisällyttää?

Sisällytä UTC-aikaleima, metodi, päätepiste, ympäristö, HTTP-tila, peitetty vastausrunko, pyynnön tunnus ja tieto siitä, toistuuko ongelma minimaalisella pyynnöllä. Kuvaa viimeaikaiset käyttöönotot tai tunnistetietojen muutokset. Älä sisällytä salaisuuksia ja peitä diagnoosiin tarpeettomat lähetystiedot.

Lähteet