Skip to main content
НачалоБлогРъководстваГрешка при удостоверяването на Tracking API: 7 причини за отговори 401/403 и как да ги отстраните

Грешка при удостоверяването на Tracking API: 7 причини за отговори 401/403 и как да ги отстраните

17TRACK

Грешка при удостоверяване на Tracking API обикновено има една от седем причини: липсващ идентификатор, неправилно форматиран заглавен ред за удостоверяване, невалидна или оттеглена тайна, несъответствие между среди, недостатъчни разрешения, изтекъл токен или невалиден подпис, или правило за сигурност, което блокира заявката. За да коригирате отговор 401 или 403, първо установете коя система го е върнала, след което проверете заявката спрямо изискванията за удостоверяване на доставчика. Повторните опити със същите идентификационни данни рядко решават основния проблем.

7 причини за грешки при удостоверяване на Tracking API и отговори 401 и 403

Това ръководство е предназначено за разработчици и екипи по интеграция, които свързват проследяването на пратки с ecommerce платформа, система за управление на поръчки, складово приложение или вътрешно табло. Започнете с една неуспешна заявка, вместо да променяте идентификационните данни в цялата интеграция.

Първо разграничете 401 от 403

HTTP дефинициите са отправна точка, но не представляват пълна диагностика. 401 Unauthorized означава, че заявката не съдържа валидни идентификационни данни за удостоверяване за целевия ресурс. 403 Forbidden означава, че сървърът е разбрал заявката, но отказва да я изпълни. Отговор 403 не доказва непременно, че удостоверяването е успешно: шлюз или услуга за сигурност може да отхвърли заявката, преди приложението да провери идентификационните данни.

Съгласно RFC 9110 сървър, който генерира отговор 401, трябва да включи предизвикателство WWW-Authenticate. Проверете това заглавие, когато е налично, но прочетете и тялото на отговора и документацията за грешки на доставчика. Различните реализации не винаги показват грешките по един и същи начин.

Какво наблюдаватеКакво да проучите първо
401 със съобщение за липсващи или невалидни идентификационни данниВмъкване на идентификационните данни, формат на заглавния ред и валидност на идентификационните данни
403 със съобщение за недостатъчни разрешенияОбхвати, достъп до акаунта, tenant и собственост върху ресурса
403 с HTML страница за сигурностШлюз, прокси, защитна стена или политика за достъп
HTTP успех с грешка в JSONПолета за грешки на ниво приложение на доставчика

Съхранявайте отделно транспортния статус и статуса на приложението в логовете. JSON поле с име code не е автоматично HTTP статус, а успешната HTTP комуникация не означава непременно, че заявената операция за проследяване е успешна.

Създайте безопасен диагностичен запис

Преди да променяте каквото и да е, запишете UTC времевия печат, HTTP метода, името на хоста, пътя, статуса на отговора, съобщението за грешка от доставчика, идентификатора на заявката и средата на внедряване. Отбележете дали отговорът идва от доставчика на проследяването, от вашия собствен backend или от междинен компонент.

Запишете имената на заглавните редове за удостоверяване и дали стойностите са налични, но никога не записвайте пълни API ключове, bearer токени, refresh токени или тайни за подписване. Избягвайте експортирането на нецензурирани трасета на заявки. Номерата за проследяване и данните за пратките също може да изискват цензуриране съгласно правилата на организацията ви за обработка на данни.

Използвайте документирана от доставчика операция с ниско въздействие, за да възпроизведете проблема. Не регистрирайте многократно пратки, не създавайте абонаменти и не променяйте настройките на webhook-и само за да тествате удостоверяването.

7 причини за отговори 401/403 от Tracking API

1. Идентификационните данни изобщо не достигат до API

Тайната може да съществува в конзолата за внедряване, без да е достъпна за работещото приложение. Често срещани точки на отказ са липсваща променлива на средата, неправилна препратка към тайна, worker, който не е рестартиран след промяна на конфигурацията, или конструктор на заявки, който пропуска празни стойности.

Прокси също може да премахне заглавен ред за удостоверяване. Обърнете внимание на пренасочванията, тъй като HTTP клиентът може да не препрати чувствителни заглавни редове към друг хост.

  • Проверка: Проверете заявката в последната надеждна изходяща точка. Потвърдете, че необходимият заглавен ред съществува и съдържа непразна стойност.
  • Корекция: Поправете съпоставянето на тайната или конструирането на заявката, след което презаредете засегнатия процес, ако е необходимо.
  • Потвърждение: Изпълнете същата операция чрез внедреното приложение, а не само от лаптопа на разработчик.

Ако локалните заявки работят, но фоновите задачи се провалят, първо сравнете конфигурацията им по време на изпълнение. Приложението и неговите workers може да получават тайните чрез различни механизми.

2. Форматът на удостоверяването е неправилен

Не всички Tracking API приемат една и съща схема за удостоверяване. Доставчикът може да изисква специален API-key заглавен ред, OAuth bearer token или подписана заявка. Поставянето на валиден ключ в Authorization: Bearer няма да помогне, ако endpoint-ът очаква различен заглавен ред.

Други грешки включват копиране на кавички в тайната, добавяне на префикс, който доставчикът не изисква, изпращане на дублирани заглавни редове за удостоверяване или използване на поле за конфигурация в SDK, което се отнася до различен метод за удостоверяване.

  • Проверка: Сравнете действителната заявка с официалния пример за точния endpoint и версия на API.
  • Корекция: Съобразете името на заглавния ред, формата на стойността и схемата за удостоверяване с документацията. Не премествайте тайната в URL като заобиколно решение.
  • Потвърждение: Сравнете минимална заявка със заявката, генерирана от SDK, като запазите идентификационните данни цензурирани.

Имената на полетата в HTTP заглавните редове не зависят от регистъра съгласно HTTP семантиката. Следователно промяната само на главни и малки букви не е обичайното решение. Съсредоточете се върху правилното поле, стойност и път на предаване.

3. Ключът е неправилен, оттеглен или вече не е внедрен последователно

Копиран ключ може да е непълен, да принадлежи към друг акаунт или да е оттеглен при промяна в сигурността. Ротацията на идентификационните данни може също да причини периодични откази: някои инстанции на приложението използват новата тайна, докато други продължават да използват старата.

Не приемайте, че всеки API ключ изтича автоматично. Правилата за изтичане и ротация зависят от доставчика и типа идентификационни данни.

  • Проверка: Потвърдете статуса на идентификационните данни в конзолата на оторизирания акаунт и сравнете внедрената версия на тайната между приложения, workers и планирани задачи.
  • Корекция: Внедрете валидни идентификационни данни чрез процеса си за управление на тайни. Ако подозирате изтичане, следвайте процедурата за инциденти и оттеглете компрометираните идентификационни данни.
  • Потвърждение: Проверете всеки засегнат път на изпълнение след внедряването. Една успешна заявка не доказва, че всяка инстанция е обновена.

Където е възможно, използвайте не-secret идентификатор на идентификационните данни или версия от secret manager, за да различавате внедряванията. Никога не искайте от клиент или колега да поставя пълен ключ в тикет към поддръжката.

4. Идентификационните данни и endpoint-ът принадлежат към различни среди

Някои услуги разделят production и test идентификационни данни, регионални endpoint-и, акаунти или tenants. Валидни идентификационни данни могат да се провалят, когато бъдат представени към грешния хост или контекст на акаунта. Тази проверка се прилага само когато доставчикът документира тези различия.

Друга възможност е остарял базов URL. Интеграцията може да използва стар endpoint, докато конфигурацията за удостоверяване вече е обновена за по-нов API.

  • Проверка: Прегледайте пълната дестинация: схема, име на хоста, версия на API, път и всеки необходим идентификатор на акаунт или tenant.
  • Корекция: Свържете идентификационните данни с предназначената им среда и endpoint. Съхранявайте URL и конфигурацията на тайните за всяка среда заедно.
  • Потвърждение: Потвърдете разрешената дестинация в работещото внедряване и проверете дали клиентът следва пренасочвания.

Избягвайте тестване на списък от предполагаеми хостове с реални идентификационни данни. Използвайте само endpoint-и, документирани от доставчика.

5. Удостоверяването е успешно, но разрешенията са недостатъчни

Идентификационните данни могат да идентифицират извикващия, без да му разрешават заявената операция. Четенето на събития за пратки, регистрирането на номера за проследяване, промяната на абонаменти и администрирането на акаунт може да изискват различни права за достъп.

Собствеността върху ресурса също има значение. Пратка, видима в едно работно пространство, може да не е достъпна чрез идентификационни данни, свързани с друго. Някои системи умишлено ограничават подробностите за грешките, така че само 403 не може да установи дали даден ресурс съществува.

  • Проверка: Проверете scopes, роли, членство в акаунта, собственост върху ресурса и специфичните за endpoint-а изисквания за достъп.
  • Корекция: Дайте само необходимото за интеграцията разрешение или използвайте правилния оторизиран акаунт.
  • Потвърждение: Тествайте неуспешната операция с ресурс, който акаунтът със сигурност може да управлява.

За OAuth bearer tokens RFC 6750 разграничава invalid_token от insufficient_scope. Когато доставчикът следва тази конвенция, първото насочва към валидността на токена, а второто — към оторизацията. Не приемайте, че всеки Tracking API използва OAuth или тези полета за грешки.

6. Токенът е изтекъл или подписът на заявката е невалиден

Удостоверяването, зависещо от времето, добавя допълнителни възможности за отказ извън неправилен статичен ключ. OAuth access token може да изтече. Подписана заявка може да бъде отхвърлена, защото времевият ѝ печат е извън допустимия интервал или защото сървърът изчислява различен подпис.

Несъответствията в подписа могат да са резултат от подписване на едно тяло на заявката и изпращане на друго, различно кодиране на пътя, промяна на query параметри или използване на грешна тайна за подписване. Тези проверки се прилагат само за API, които документират подписани заявки.

  • Проверка: Проверете изтичането на токена и резултатите от обновяването. За подписи сравнете документираната канонична заявка с точните изпратени байтове и полета.
  • Корекция: Обновете или получете токени чрез поддържания flow, синхронизирайте системното време и генерирайте подписи след окончателното определяне на компонентите на заявката.
  • Потвърждение: Тествайте следващия момент за обновяване на токена, а не само непосредствено след получаването на нов токен.

В системи с множество workers координирайте обновяването на токените, за да не презаписват workers многократно използваеми идентификационни данни или да предизвикват конкуриращи се опити за обновяване. Съхранявайте refresh token-ите отделно и защитено от обикновените логове на заявките.

7. Шлюз, защитна стена или мрежова политика блокира заявката

403 може да произхожда извън приложението за проследяване. Възможните причини включват несъответствие в IP allowlist, политика на изходящо прокси, правило на web application firewall или шлюз за достъп, който изисква собствена оторизация.

HTML страница за отказ, непознат заглавен ред в отговора или специфичен за шлюза идентификатор на заявката могат да помогнат за идентифициране на слоя, който отхвърля заявката. Това са подсказки, а не доказателства; потвърдете ги чрез логовете на шлюза или екипа за поддръжка на доставчика.

  • Проверка: Сравнете публичния изходящ IP адрес и мрежовия маршрут на неуспешното внедряване с тези на позната работеща среда.
  • Корекция: Коригирайте съответния allowlist, конфигурацията на проксито или тясно обхванатото правило за сигурност чрез отговорния инфраструктурен екип.
  • Потвърждение: Повторете заявката от първоначалната среда за изпълнение след промяната на политиката.

Не деактивирайте проверката на TLS сертификатите и не заобикаляйте широко контролите за сигурност. Браузърните CORS грешки също изискват отделна диагностика: проверете дали отхвърлената заявка е preflight заявка OPTIONS или действителното API извикване. Дълготрайните тайни на Tracking API не трябва да се излагат в browser код.

Използвайте минимална заявка за изолиране на проблема

Сведете неуспешното извикване до документирания endpoint, метода, необходимото удостоверяване и най-малкия валиден payload. Следващият пример е общ диагностичен шаблон, а не работеща заявка за конкретен доставчик:

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

Добавете необходимия content type и body, ако операцията ги изисква. Използвайте това само в контролирана среда: аргументите на командата, записите на терминала и диагностичните инструменти могат да разкрият тайни. Избягвайте подробни трасета, освен ако не можете да защитите и цензурирате изхода им.

Ако минималната заявка е успешна, но приложението се проваля, проверете конфигурацията на SDK, конструирането на заглавните редове, пренасочванията, поведението на проксито и тайните по време на изпълнение. Ако и двете се провалят, проучете валидността на идентификационните данни, избора на endpoint, разрешенията и мрежовата политика. Променяйте по една променлива наведнъж, така че резултатът да посочи причината.

Прилагане на проверките към интеграция с 17TRACK

За интеграция с 17TRACK Tracking API започнете с официалната API документация и съобразете инструкциите за удостоверяване и формата на заявката с операцията, която извиквате. Не замествайте схема за удостоверяване, копирана от несвързан API, и не приемайте, че достъпът до потребителска страница за проследяване потвърждава API оторизацията.

Сравнете документираната заявка със заявката, която напуска сървъра ви, след което проверете както HTTP отговора, така и документираните полета на отговора. Ако е необходимо ескалиране, изпратете цензуриран пример, времеви печат, endpoint, подробности за отговора и идентификатор на заявката, когато е наличен. Не включвайте API тайната в отчета.

Спрете сляпото повторение и потвърдете възстановяването

Грешките при удостоверяване трябва да задействат диагностика, а не неограничен цикъл от повторни опити. При изрично изтекъл токен контролирано обновяване, последвано от ограничен повторен опит, може да е подходящо. При липсващи разрешения, оттеглени идентификационни данни или блокиран мрежов път повторните опити няма да поправят конфигурацията.

Преди да повторите write операция, проверете поведението на доставчика за idempotency или обработка на дубликати. Това е важно, когато междинен компонент прави първоначалния резултат неясен.

Възстановяването е завършено, когато планираната операция успее от първоначалното внедряване, всички съответни workers използват правилната конфигурация и мониторингът не показва продължаващи грешки при удостоверяване. Проследявайте отделно HTTP статусите и грешките на ниво приложение, с известия, които идентифицират засегнатия endpoint и среда, без да разкриват идентификационни данни.

Често задавани въпроси

Защо заявката работи локално, но се проваля в production?

Сравнете версиите на тайните, базовите URL адреси, изходящите прокси сървъри, egress IP адресите, системните часовници и конфигурацията по време на изпълнение. Локалният успех показва, че един път на заявката работи; той не доказва, че production изпраща същата заявка или има същите разрешения.

Трябва ли веднага да генерирам нов API ключ?

Не, освен ако текущите идентификационни данни не са невалидни, оттеглени или потенциално изложени. Първо проверете дали достигат до правилния endpoint в необходимия формат. Ненужната ротация може да причини откази в други услуги, които все още зависят от съществуващия ключ.

Може ли неправилен номер за проследяване да причини 401 или 403?

Невалидният номер за проследяване обикновено е въпрос на валидация или ресурс, а не доказателство за невалидно удостоверяване. Достъпът до пратка обаче може да бъде ограничен от собствеността върху акаунта. Използвайте документираните подробности за грешки на доставчика, вместо да поставяте диагноза само по номера.

Означава ли 403, че абонаментът ми за API е изтекъл?

Не. Ограниченията на абонамента или правото на използване са само една възможност и то ако доставчикът ги документира или върне конкретно съобщение. Разрешенията, контекстът на акаунта и политиките за сигурност също могат да причинят отказ. Не извеждайте проблем с таксуването само от HTTP статуса.

Какво трябва да включа в заявка към поддръжката?

Включете UTC времевия печат, метода, endpoint-а, средата, HTTP статуса, цензурираното тяло на отговора, идентификатора на заявката и дали проблемът се възпроизвежда с минимална заявка. Опишете скорошни внедрявания или промени в идентификационните данни. Изключете тайните и цензурирайте данните за пратки, които не са необходими за диагностиката.

Източници

  • RFC 9110: HTTP Semantics — удостоверяване чрез HTTP, семантика на заглавните редове и дефинициите на 401 и 403.
  • RFC 6750: OAuth 2.0 Bearer Token Usage — отговори за грешки при bearer token, невалидни токени и недостатъчен обхват.
  • 17TRACK API documentation — специфичната за доставчика справка за внедряване и отстраняване на проблеми със заявка към 17TRACK API.