Ракување со грешки во Tracking API: Како да управувате со невалидни броеви за следење, ограничувања на стапката и повторни обиди

Справувајте се со грешките на API-то за следење така што ќе ги одделите невалидниот внес, привремените неуспеси, ограничувањата на стапката и резултатите од статусот на пратката. Одбивајте ги или исправете ги невалидните броеви за следење наместо повторно да ги испраќате непроменети, координирајте го обемот на барањата кога е достигнато ограничувањето и повторувајте ги привремените неуспеси со ограничено експоненцијално повратно доцнење и случајно отстапување. Пред да повторите регистрација или друго барање за запишување, утврдете дали првиот обид бил успешен.

За програмерите што ги поврзуваат податоците за следење со систем за управување со нарачки, платформа за магацин или страница за следење наменета за корисници, целта не е едноставно да има помалку неуспешни барања. Целта е сигурна видливост на пратките без дупликатни регистрации, бура од повторени обиди, погрешни пораки за испорака или непотребни барања до поддршката.

Класифицирајте го неуспехот пред да изберете одговор

Интеграцијата за следење има неколку одделни исходи што треба да се проценат: дали мрежното барање завршило, дали API-то ја прифатило операцијата, дали секоја побарана ставка за следење била успешна и дали се достапни настани за пратката. Третирањето на сите четири како едно единствено знаме за успех или неуспех создава грешки што може да се избегнат.

Успешниот HTTP одговор не значи нужно дека секоја ставка во серијата била успешна. Спротивно, успешно обработеното пребарување без настани за следење не е нужно неуспех на API-то. Проверете го телото на одговорот и применете го документираното значење на давателот за секој резултат.

Услов	Препорачано дејство	Повторно испраќање непроменето?
Погрешно форматиран број или невалидно поле во барањето	Проверете го и исправете го внесот	Не
Недостиг или невалидност на акредитивите	Проверете ги акредитивите, дозволите и околината	Не додека не се исправи
Одговор со ограничување на стапката	Одложете ја засегнатата работа и намалете го заедничкиот притисок од барањата	По задолжителното чекање, ако е безбедно
Привремен неуспех на услугата	Применете ограничено повратно доцнење и проверете ја безбедноста на операцијата	Обично, во рамките на буџетот за повторни обиди
Истек на времето по испраќање регистрација	Усогласете дали регистрацијата постои	Не слепо
Прифатено пребарување без настани за пратката	Следете го документираниот животен циклус на следењето	Користете закажано освежување, а не брзи повторувања

HTTP статусните кодови се почетна точка, а не целосно одлучувачко правило специфично за давателот. RFC 9110 ја дефинира семантиката на HTTP, додека RFC 6585 го дефинира 429 Too Many Requests. Вашата интеграција треба да ги толкува и документираните кодови за грешки на апликацијата и резултатите на ниво на ставка.

Невалидни броеви за следење: разликувајте погрешен внес од недостиг на настани

„Невалиден број за следење“ може да опишува различни проблеми: погрешно форматиран идентификатор, неподдржана комбинација на превозник и број, недостиг на задолжително поле за превозник или друг неуспех при проверка специфичен за давателот. Не претпоставувајте дека бројот е невалиден само затоа што не се вратени настани за следење.

Проверувајте без да го оштетите идентификаторот

• Чувајте ги броевите за следење како текстуални низи. Нумеричкото складирање може да ги отстрани почетните нули или да ги измени долгите идентификатори.
• Зачувајте го оригиналниот внес. Чувајте одделна нормализирана вредност за трансформациите да можат да се проверуваат.
• Нормализирајте внимателно. Отстранете ги околните празни места кога е соодветно, но отстранувајте внатрешни знаци или менувајте ја големината на буквите само кога документираните правила го дозволуваат тоа.
• Проверете ги локално задолжителните полиња. Фатете празни броеви, недостасувачки идентификатори на превозникот и невалидни структури на барањето пред да ги испратите.
• Избегнувајте универзален регуларен израз за броеви за следење. Правило наменето за еден превозник може да одбие валидни идентификатори од друг.
• Потврдете што содржи полето. Бројот на нарачката, референцата на магацинот и бројот за следење на превозникот не се меѓусебно заменливи, освен ако крајната точка изречно ги поддржува.

Ако API-то изречно го одбие внесот, насочете го кон исправка наместо кон автоматска јамка за повторување. Наведете корисна причина, како „потребен е идентификатор на превозникот“, наместо секој проблем при проверката да го сведувате на „следењето не успеа“.

Третирајте го „нема настани“ како одделна состојба

Пратката може да има идентификатор за следење пред да станат достапни корисни настани за движењето. Точниот одговор зависи од документираниот модел на статуси на API-то и од контекстот на пратката. Проверете дали идентификаторот потекнува од системот за испорака, дали изборот на превозник е точен и дали одговорот укажува на податоци што се очекуваат, а не на одбиен внес.

Користете одделни внатрешни состојби како input_rejected, awaiting_events и temporarily_unavailable. Ова се предложени состојби на апликацијата, а не стандардизирани вредности на API-то. Тие помагаат привремениот недостиг на податоци да не се претвори во неточна порака до корисникот.

Управувајте со ограничувањата на стапката низ целата интеграција, а не по работник

RFC 6585 го дефинира HTTP 429 како одговор за ограничување на стапката и дозволува да содржи заглавие Retry-After. Стандардот не утврдува универзално дозволено количество или метод на броење за API за следење. Ограничувањата може да бидат документирани според сметка, акредитив, крајна точка или друг опсег; користете ги фактичките правила на давателот.

RFC 9110 наведува два облика на Retry-After: ненегативен број секунди или HTTP датум. Парсирајте ги двата. Ако вредноста е датум, внимателно пресметајте го преостанатото чекање и земете ги предвид разликите во часовниците. Ако недостасува или не може да се употреби, применете ја конфигурираната резервна политика за повратно доцнење.

Спиењето на еден работник независно не е доволно кога другите работници продолжуваат да го користат истиот лимит. Поставете контрола на стапката на заедничката граница за релевантниот акредитив или сметка. Централен распоредувач, заедничка кофа со токени или еквивалентна дистрибуирана контрола може да го координира тој сообраќај.

1. Идентификувајте го засегнатиот опсег. Утврдете на која крајна точка, акредитив или сметка се однесува ограничувањето.
2. Почитувајте ја инструкцијата за чекање од серверот. Не закажувајте порано повторување од она што го дозволува валидната вредност на Retry-After.
3. Одложете ја засегнатата работа во редицата. Избегнувајте блокирање неповрзан сообраќај кога ограничувањата навистина се независни.
4. Намалете ја конкурентноста или зачестеноста на барањата. Еднократното чекање без промена на образецот на барања може повторно да го создаде истиот проблем.
5. Продолжете со временски растојанија. Не ослободувајте ја целата заостаната работа истовремено кога ќе заврши чекањето.

Кога е поддржано, групното испраќање може да го намали бројот на барања, но мора да ги почитува документираните правила за големина на серијата и пресметување. Не претпоставувајте дека една серија троши една единица од дозволеното количество. Исто така, користете веб-куки каде што се достапни за да го намалите непотребното периодично испитување, при што задржете го процесот на усогласување што го бара вашата интеграција.

Користете ограничени повторни обиди со повратно доцнење и случајно отстапување

Повторните обиди се соодветни кога неуспехот може да се отстрани без промена на барањето и кога повторувањето на операцијата е безбедно. Привремените прекини на врската и избрани серверски грешки може да спаѓаат во таа категорија. Погрешно формиран товар, невалиден акредитив или траен проблем со дозволите обично бара исправка.

Практична резервна опција е ограничено експоненцијално повратно доцнење со целосно случајно отстапување:

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

Овде, retry_index започнува од нула за првиот повторен обид, а отсуството на Retry-After не додава дополнително минимално чекање. Ова се избори при имплементацијата, а не задолжителен алгоритам на HTTP. Изберете основно доцнење, горна граница, ограничување на обидите и вкупен рок според вашето оптоварување и упатствата на давателот.

Случајното отстапување ги распоредува барањата низ времето наместо секој работник да ги повторува според истиот распоред. Горната граница на доцнењето ја ограничува експоненцијалната компонента; таа не треба да го надмине подолгото валидно чекање побарано од серверот. Ако тоа чекање го надминува рокот на задачата, одложете ја или прекинете ја задачата според политиката, наместо да повторувате прерано.

На секоја низа повторни обиди дадете крајна точка

• Ограничување на обидите: ограничете го бројот на дополнителни барања.
• Ограничување според изминато време: престанете да повторувате работа што го надминала својот корисен временски прозорец за обработка.
• Изречна одговорност: изберете кој слој ги контролира повторните обиди за повторните обиди на HTTP-клиентот и редицата да не се умножуваат неочекувано.
• Трајно закажување: складирајте ги одложените задачи наместо да се потпирате на долго спиење во краткотрајни процеси.
• Патека за обновување: испратете ги исцрпените задачи во проверлива редица за неуспешни задачи со причина и следно дејство.

При долготраен прекин, разгледајте прекинувач на колото што привремено ги паузира рутинските повици и дозволува контролирани сонди за обновување. Ова е образец за отпорност на апликацијата, а не доказ дека некој конкретен давател на следење го бара.

Разрешете ги нејасните запишувања пред повторно да ги испратите

Истекот на времето ви кажува дека вашата апликација не добила целосен одговор. Не докажува дека серверот го одбил или никогаш не го обработил барањето. Оваа разлика е важна при регистрирање броеви за следење или промена на конфигурацијата за следење.

RFC 9110 ги објаснува идемпотентните методи и предупредува против автоматско повторување на неидемпотентни барања без основа за заклучок дека повторувањето е безбедно или дека оригиналната операција не била применета. Проценете ја документираната семантика на операцијата наместо да претпоставувате дека секоја крајна точка за следење се однесува како пребарување само за читање.

• Користете механизам за идемпотентност документиран од давателот кога е достапен, следејќи ги неговите правила за опсег и задржување.
• Задржете го истиот клуч за идемпотентност при повторни обиди на истата логичка операција; не претпоставувајте дека произволно сопствено заглавие ќе биде прифатено.
• Ако е поддржано, проверете ја постојната регистрација пред да повторите нејасно запишување.
• Користете локално ограничување за единственост усогласено со документираниот идентитет на пратката кај давателот.
• Зачувајте го исходот на операцијата за повторната испорака од редицата автоматски да не предизвика ново запишување.

За сериски операции, зачувајте го резултатот на секоја ставка. Повторувајте само ставки класифицирани како привремено неуспешни и усогласете ги ставките чии исходи остануваат непознати. Повторното пуштање на целата серија може да ја повтори успешната работа и непотребно да го потроши дозволеното количество барања.

Применете ја политиката кај вашиот давател на услуги за следење

За интеграција со 17TRACK, користете ја страницата Tracking API и официјалната API документација како почетни точки за договорот специфичен за давателот. Класификаторот на грешки нека биде конфигурабилен, наместо да внесувате претпоставки од општ водич за HTTP.

Пред имплементацијата, потврдете ја шемата на барањето на релевантната крајна точка, обвивката на одговорот, значењата на грешките на ниво на ставка, опсегот на ограничувањето на стапката, ограничувањата за серии и правилата за дупликатни испраќања. Кога користите испорака на настани, проверете ги и барањата за потврда, автентикација и повторна испорака. Овој водич не пропишува нумеричко ограничување на стапката, распоред за повторни обиди или функција за идемпотентност на 17TRACK.

Запишете го секое потврдено правило во мапирање од одговорот на давателот кон дејство на апликацијата: исправете го внесот, поправете ја конфигурацијата, почекајте, усогласете или ескалирајте. Непрепознаена грешка треба да го зачува дијагностичкиот контекст и да следи ограничена резервна патека, а не да премине на неограничени повторни обиди.

Следете го квалитетот на обновувањето и тестирајте ги патеките за неуспех

Евидентирајте ја операцијата, крајната точка, HTTP статусот, кодот за грешка на апликацијата, бројот на обидот, доцнењето, следното закажано дејство и идентификаторот на барањето кај давателот кога е доставен. Избегнувајте запишување API клучеви, непотребни адресни информации или неограничени тела на одговори. Маскирајте ги или хеширајте ги идентификаторите за следење кога не се потребни целосните вредности.

Следете ги одделно стапките на невалиден внес, ограничувањето на стапката, староста на редицата, исцрпените повторни обиди и последната успешна синхронизација. Интеграцијата може да има ниска стапка на HTTP грешки, а сепак да прикажува застарени информации за пратките. Страниците наменети за корисници треба да го задржат последниот познат статус на пратката и да разликуваат неуспех при освежување од исклучок при испорака пријавен од превозникот.

Пред објавување, тестирајте погрешно форматиран внес, валидни идентификатори без настани, двата облика на Retry-After, заглавија што недостасуваат, делумни неуспеси на серии, истек на времето по запишувања и повторна испорака од редицата. Исто така, симулирајте прекин доволно долг за да се исцрпи буџетот за повторни обиди. Тестот е успешен само кога работата запира или се одложува предвидливо, успешните ставки не се повторуваат непотребно и неуспешните ставки остануваат обновливи.

Често поставувани прашања

Дали невалиден број за следење треба автоматски да се повтори?

Не, кога API-то изречно го одбива внесот како невалиден. Прво исправете го бројот, изборот на превозник или задолжителните полиња. Ако одговорот наместо тоа значи дека настаните за пратката сè уште не се достапни, користете го документираниот процес за освежување наместо да го третирате како неуспех при проверката.

Дали HTTP 200 значи дека сериското барање било целосно успешно?

Не нужно. Проверете ја шемата на одговорот на давателот за резултати на ниво на операција и ставка. Зачувајте ги успешните ставки и изолирајте ги неуспешните за повторувањето на една ставка непотребно да не ги повтори останатите.

Колку повторни обиди треба да дозволи интеграцијата за следење?

Не постои универзален број. Поставете и ограничување на обидите и буџет според изминатото време врз основа на упатствата на давателот, безбедноста на операцијата и времетраењето во кое резултатот останува корисен. Закажаната синхронизација во заднина може да поднесе поинаков прозорец за обновување од интерактивното барање на корисник.

Дали истекот на времето треба веднаш да ја означи пратката како неуспешна?

Не. Истекот на времето на барањето е исход на интеграцијата, а не настан за пратката. Зачувајте ја последната позната состојба на следењето, закажете безбедно обновување и избегнувајте проблемот со поврзувањето да го претворите во известување за неуспешна испорака.

Што треба да се случи кога ќе се исцрпат повторните обиди?

Преместете ја задачата во трајна редица за неуспешни задачи или за проверка, заедно со нејзиниот дијагностички контекст. Утврдете дали обновувањето бара исправен внес, обновени акредитиви, помош од давателот или подоцнежно контролирано повторно извршување. Не ја отфрлајте тивко и не ја започнувајте повторно истата неограничена низа обиди.

Извори

• RFC 9110: HTTP Semantics — семантика на HTTP статусите, идемпотентни методи, размислувања за автоматско повторување и полето Retry-After.
• RFC 6585: Additional HTTP Status Codes — дефиницијата на 429 Too Many Requests и неговото изборно заглавие Retry-After.
• 17TRACK Tracking API — официјална почетна точка за производот Tracking API.
• 17TRACK API documentation — референца за проверка на специфичните барања за интеграција на давателот.