Duplikált posztok elkerülése közösségi média API-ban 2026-ban: idempotencia és retry

A duplikált közösségi média posztok elkerüléséhez két különböző hibahatárt kell külön kezelned: a kliens és az API közötti beküldési újrapróbálásokat (amelyeket az Idempotency-Key fejléc és az adatbázis unique indexei védenek), valamint a worker és a célplatform közötti publikálási újrapróbálásokat (ahol csak a tartalom létrehozása előtti, úgynevezett pre-commit lépéseket szabad automatikusan megismételni). Ha a hálózati kapcsolat a végső közzétételi hívás közben szakad meg az Instagram, a TikTok, a Facebook vagy a LinkedIn felé, a kimenetel ismeretlen — az automatikus újrapróbálás pedig kétszer teheti ki ugyanazt a videót.

Ha most állítod össze a többplatformos közzétételi folyamatodat YouTube-ra, TikTokra és Instagramra, vagy a TikTok Content Posting API útmutatónkat (angolul) követed, ez a cikk azt az adatbázis-, sor- és retry-architektúrát mutatja be, amely megakadályozza, hogy egy hálózati hiba duplikált posztot okozzon.

Miért posztol kétszer a naiv HTTP-újrapróbálás?

Ahogy az RFC 9110 9.2.2-es szakasza rögzíti, a POST nem idempotens HTTP-metódus: egy POST kérés megismétlése kapcsolatbomlás vagy gateway timeout után nem garantálja, hogy a szerver csak egyszer hajtja végre a műveletet. A közösségi média publikálásban egyetlen poszt két hálózati szakaszon halad át:

1. A saját alkalmazásod és a publikáló API között: Az n8n-folyamatod, a háttérfolyamatod vagy a szervered meghívja a POST /uploads/start vagy a POST /videos/import végpontot. Ha egy proxy 502 Bad Gateway hibát ad, vagy a kliens időtúllépést érzékel, miután a szerver már elmentette a tranzakciót, a vakon újrapróbálkozó kliens második publikálási kérést hoz létre.

2. A publikáló worker és a közösségi platform között: Az Uplonic workere feltölti a videóbájtokat, majd elküldi a végső közzétételi kérést a TikTok, az Instagram, a Facebook, a YouTube vagy a LinkedIn felé. Ha az Instagram media_publish vagy a Facebook reel_finish hívásának válasza közben ECONNRESET vagy ETIMEDOUT történik, a platform ettől még közzétehette a posztot.

Az a kérdés, hogy „átmeneti-e a hiba”, szükséges, de nem elégséges feltétel az automatikus újrapróbáláshoz. Ahogy az Uplonic retry-szabályzata kimondja, a valódi kérdés így szól: bizonyítható-e, hogy a platformon nem jött létre tartalom?

1. védelmi vonal: Kliensszintű idempotencia az importnál és a publikálásnál

Az első hálózati szakaszon úgy állítható meg a duplikáció, ha a szerver felismeri az ismételt logikai kérést, és — még két egyidejű kérés versenyhelyzetében is — az eredeti rekordot adja vissza. Az Uplonic ezt mind a videóimportnál, mind a publikálási sornál adatbázis-szinten kényszeríti ki:

Amikor Idempotency-Key fejléccel küldesz kérést, a createPublishRequest egyetlen tranzakcióban menti el a PublishRequest és az összes PublishTask sort a HTTP 202 válasz előtt. Ha két párhuzamos újrapróbálás ugyanabban az ezredmásodpercben ér célba, az adatbázis unique indexe P2002 kóddal megállítja a másodikat, a hibakezelő ág pedig azonnal visszaadja a nyertes kérést deduplicated: true jelzéssel.

2. védelmi vonal: Pre-commit és commit műveletek szétválasztása a workerben

Miután a worker felvette a PublishTask feladatot, a kliens által küldött idempotenciakulcs már nem védi meg a külső platformhívást, mivel a legtöbb közösségi hálózat API-ja nem fogad idempotenciakulcsot posztlétrehozáskor. Ezért a decideRetry függvény azt vizsgálja, hogy a többlépéses feltöltés melyik műveleténél keletkezett a hiba.

Figyeld meg, miért hiányzik szándékosan a pull_url_init (a TikTok PULL_FROM_URL módja) és a Facebook upload_via_url művelete a PRE_COMMIT_OPERATION_PREFIXES listából. A darabolt fájlfeltöltéssel szemben ezek egyetlen hívással utasítják a platformot a videó letöltésére és közzétételére: ha a kapcsolat a válasz megérkezése előtt szakad meg, a megismételt hívás második posztot indítana el.

Hasonló védelem működik az Instagram és a Threads konténeres publikálásánál is: az Uplonic státuszlekérdezője a media_publish meghívása előtt ellenőrzi a konténer állapotát. Kizárólag FINISHED állapotú konténert publikál, a mutáló hívás előtt feltételes leaseOwner frissítéssel (extendPollClaim) hosszabbítja meg a foglalást, a már PUBLISHED állapotban lévő konténert pedig újabb media_publish hívás nélkül sikeresként zárja le.

3. védelmi vonal: Az unknownOutcome kezelése és a taskonkénti kézi újraindítás

Amikor egy task a commit határon túl, bizonytalan kimenetellel szakad meg, az Uplonic unknownOutcome = true jelzéssel állítja le az automatikus újrapróbálást. Amikor később a POST /uploads/requests/:id/retry végpontot hívod (retryPublishTasks), három szabály védi a fiókot:

• Taskonkénti izoláció: Ha egy kérés YouTube-ra, TikTokra és Instagramra ment, és csak az Instagram bukott el, az újrapróbálás kizárólag az elbukott PublishTask sort teszi vissza a sorba — a sikeres csatornákhoz nem nyúl.

• Megerősítési kapu ismeretlen kimenetelnél: Alapértelmezés szerint (confirmUnknownOutcome: false) a retryPublishTasks kihagyja az unknownOutcome: true taskokat, és a skipped[] tömbben adja vissza őket code: "unknown_outcome" és needsConfirmation: true jelzéssel. Csak akkor küldd el a confirmUnknownOutcome: true paramétert, ha ellenőrizted a célfiókot, és a poszt valóban nem jelent meg.

• Előzetes állapotellenőrzés: Újraindítás előtt a retryPublishTasks azt is ellenőrzi, hogy a csatornakapcsolat aktív-e (platform_disconnected), és a médiafájl nem törlődött-e a megőrzési idő lejártával (media_deleted).

Ahhoz, hogy a végső kimeneteleket folyamatos lekérdezés (polling) nélkül kövesd, egészítsd ki az idempotens beküldést aláírt eseményértesítésekkel — erről szól a közösségi média publikálási webhookokat bemutató cikkünk és az API-integrációs szolgáltatásunk.