Integrationer og stabil drift

Eksterne API-kald: undgå at appen hænger eller gør det samme to gange

En integration kan virke hver gang i en demo og stadig være usikker i drift. Netværket kan afbrydes, leverandøren kan være langsom, eller svaret kan forsvinde efter, at en booking, betaling eller faktura faktisk er oprettet. Appen skal derfor kunne stoppe et langsomt kald, skelne mellem fejl og undgå at gentage en handling ukritisk.

Kortlæg konsekvensen før retry-reglen

Tag udgangspunkt i de eksterne kald, der indgår i et vigtigt brugerforløb. Skriv ned, hvad leverandøren kan have nået at gøre, hvis appen ikke modtager et svar. Det afgør, om et nyt forsøg er sikkert.

Handling	Risiko ved uklart svar	Sikker adfærd
Hent en produktliste	Brugeren ser ingen eller gamle data	Kort timeout, begrænset retry eller tydeligt mærket cache
Opret en booking	Samme booking kan blive oprettet flere gange	Stabil idempotensnøgle og efterkontrol af status
Send en faktura	Kunden kan modtage dubletter	Gem intern reference og bekræft leverandørens resultat
Synkronisér en status	Systemerne kan ende med forskellig sandhed	Registrér ønsket status, seneste forsøg og afstemning

“Intet svar” betyder ikke “intet skete”. Brug derfor en mellemstatus som “afventer bekræftelse”, når appen ikke kan bevise, om leverandøren udførte handlingen.

Sæt en timeout på hvert udgående kald

Uden en eksplicit timeout kan et langsomt afhængigt system holde webrequests, forbindelser og serverressourcer optaget. Timeouten skal omfatte den tid, appen reelt vil vente – og den skal passe til brugerforløbet. Der findes ikke ét korrekt antal sekunder for alle integrationer.

Interaktivt kald: Brugeren skal have et svar hurtigt nok til at forstå, om handlingen fortsætter, fejlede eller afventer bekræftelse.
Baggrundsarbejde: En import eller rapport kan ofte vente længere, men må stadig have en samlet tidsgrænse og en synlig jobstatus.
Flere kald i kæde: Hvert led skal have mindre tid end hele brugerforløbets samlede tidsbudget, så det yderste lag kan nå at reagere ordentligt.
Runtime og SDK: Brug platformens dokumenterede afbrydelsesmekanisme. I understøttede Node.js-versioner kan et AbortSignal udløses efter en valgt forsinkelse.

En timeout annullerer ventetiden – ikke nødvendigvis handlingen hos leverandøren. Hvis forbindelsen brydes efter, at leverandøren har modtaget requesten, skal appen stadig kunne genfinde eller afstemme resultatet.

Retry kun fejl, der kan være midlertidige

Et nyt forsøg hjælper kun, hvis fejlen sandsynligvis kan forsvinde af sig selv. Læs leverandørens aktuelle dokumentation og SDK-standarder; statuskoden alene fortæller ikke altid hele historien.

Netværksfejl, timeout, 429 og nogle 5xx: Kan være midlertidige. Retry kun når handlingen er sikker at gentage, og respekter leverandørens regler.
400, 401, 403 og de fleste 404: Peger normalt på ugyldigt input, adgang eller en forkert ressource. Samme request bliver ikke bedre af at blive gentaget.
Retry-After: Hvis leverandøren sender headeren, skal ventetiden indgå i retry-strategien frem for at blive erstattet af et hurtigere lokalt gæt.
Ugyldigt eller uventet svar: Behandl svaret som ubetroet. Valider format og betydning, og send ikke samme skrivehandling igen uden sikker identifikation.

Gør skrivehandlinger sikre at gentage

HTTP-standardens GET, PUT og DELETE er defineret som idempotente metoder, mens POST ikke automatisk er det. Den konkrete leverandør kan dog have andre garantier eller tilbyde en idempotensnøgle. Appen skal følge leverandørens dokumentation – ikke gætte ud fra metoden alene.

Opret en stabil nøgle for forretningshandlingen. Samme bookingforsøg skal genbruge samme nøgle; et nyt bevidst forsøg skal have en ny.
Gem nøglen før kaldet. Registrér intern reference, ønsket handling og status, så et procesnedbrud ikke sletter sporene.
Send nøglen som leverandøren kræver. Navn, levetid og garantier varierer. Hvis leverandøren ikke understøtter nøgler, brug dens søge- eller statusfunktion til afstemning.
Genbrug ikke nøglen til ændret indhold. En nøgle skal identificere én bestemt forretningshandling, ikke en bruger eller en knap for altid.
Vis en sand status. Skriv “gennemført” først, når appen har en bekræftelse, den kan knytte til den interne reference.

Den separate guide om samtidige ændringer og dubletter går dybere i databaseunikhed, transaktioner og idempotens på appens egen side.

Begræns retries med backoff og jitter

Et retry skal have en øvre grænse for både antal forsøg og samlet varighed. Vent længere mellem forsøgene, og læg en lille tilfældig forskydning – jitter – ind, så mange appinstanser ikke rammer den pressede leverandør samtidigt.

Brug højst ét bevidst retry-lag. Tre forsøg i både SDK, service og jobkø kan blive til langt flere kald end forventet.
Kontrollér SDK'ets indbyggede retries, før I tilføjer jeres egne.
Hold interaktive retries korte. Flyt længerevarende arbejde til en kø, hvis brugerens request ellers står åben.
Brug et samlet retry-budget, hvis mange samtidige requests kan ramme samme afhængighed.
Stop med at prøve, når fejlen er permanent, tidsbudgettet er brugt, eller den eksterne tjeneste beder jer vente længere.

Luk midlertidigt for en afhængighed, der bliver ved med at fejle

En circuit breaker kan stoppe nye kald, når fejlene passerer en aftalt grænse. I åben tilstand fejler kald hurtigt; efter en pause kan et begrænset antal prøve kald afgøre, om tjenesten er tilbage. Det beskytter både appens ressourcer og leverandøren mod en retry-storm.

Mønstret er ikke et krav til alle små apps. Indbyggede SDK-retries, en jobkø eller en enkel afbryder kan være nok. Brug circuit breaker, når en langsom eller ustabil afhængighed ellers kan få resten af appen til at stå stille, og overvåg hver ændring i dens tilstand.

Planlæg en ærlig nødadfærd

Stabil drift betyder ikke, at alle eksterne tjenester altid virker. Det betyder, at appen svigter afgrænset og fortæller sandheden, når en afhængighed er nede.

Læsning: Vis eventuelt senest kendte data med tydelig alder og uden at kalde dem aktuelle.
Skrivning: Gem arbejdet som afventende, hvis processen kan fortsætte sikkert senere; ellers bevar brugerens input og forklar, at handlingen ikke er bekræftet.
Kritisk handling: Blokér kontrolleret, hvis et usikkert fallback kan skabe økonomisk eller juridisk skade.
Manuel drift: Giv en administrator mulighed for at finde, afstemme og genkøre fejlede handlinger uden at redigere direkte i databasen.

Log ét samlet integrationsforløb

Hvert forløb skal kunne følges uden at logge adgangstokens, fulde request bodies eller unødvendige persondata. Brug en intern korrelations-id og leverandørens request-id, når den findes.

Registrér integration, operation, forsøg, varighed, resultatkategori og næste planlagte handling.
Skeln mellem timeout, netværksfejl, throttling, permanent afvisning, ugyldigt svar og åben circuit breaker.
Mål hele forløbets tid – ikke kun det forsøg, der lykkedes.
Alarmér på stigende fejlrate, retries, samlet latenstid, køalder og handlinger, der bliver stående uden endelig status.
Lav en runbook med leverandørens statusside, kontaktvej, sikker genkørsel og afstemning.

Test de svar, der ikke kommer i demoen

Brug en kontrolleret teststub eller leverandørens sandbox. Fremtving forsinkelse, afbrudt forbindelse, 429 med Retry-After, udvalgte 5xx-svar, ugyldigt JSON og et svar, der forsvinder efter en oprettelse.

Kontrollér at timeouten faktisk afbryder ventetiden og frigiver ressourcer.
Bekræft at permanente fejl ikke bliver gentaget.
Bekræft at samme idempotensnøgle ikke skaber to bookinger, betalinger eller fakturaer.
Test mange samtidige fejl, så retries ikke bliver en belastning i sig selv.
Kontrollér hvad brugeren ser, mens resultatet er ukendt, og efter en senere afstemning.
Øv genkørsel fra den interne driftsvisning med en kopi af produktionslignende, men ikke følsomme testdata.

Typiske fejl

Ingen timeout: Et enkelt langsomt system binder appens forbindelser og gør andre funktioner langsomme.
Retry af alle fejl: Ugyldigt input og manglende adgang sendes igen uden mulighed for at lykkes.
POST gentages blindt: Leverandøren nåede handlingen, men appen modtog ikke svaret.
Retry i flere lag: SDK, backend og jobkø forstærker hinanden under nedbrud.
Ingen jitter: Alle instanser prøver igen på samme tidspunkt og skaber en ny belastningstop.
Fejl vises som succes: Brugeren tror, at bookingen eller fakturaen er oprettet, selv om status er ukendt.
Cache vises som aktuelle data: Nødvisningen skjuler, at priser, lager eller status kan være forældet.
Tokens logges: Fejlsøgning skaber et nyt sikkerhedsproblem.

Tjekliste til stabile eksterne API-kald

☐ Kritiske eksterne kald og deres forretningskonsekvens er kortlagt.
☐ Hvert kald har en eksplicit timeout og et samlet tidsbudget.
☐ Fejl er opdelt i midlertidige, permanente og ukendte resultater.
☐ Leverandørens SDK-retries og aktuelle dokumentation er gennemgået.
☐ Retries er afgrænsede og bruger backoff, jitter og eventuel Retry-After.
☐ Skrivehandlinger gentages kun med dokumenteret idempotens eller sikker afstemning.
☐ Samme handling har en stabil intern reference og idempotensnøgle.
☐ Appen kan vise “afventer bekræftelse” uden at love et resultat.
☐ Vedvarende fejl stopper hurtigt eller flyttes til kontrolleret behandling senere.
☐ Logs binder forsøgene sammen uden secrets og unødvendige persondata.
☐ Alarmer dækker fejlrate, retries, latenstid og fastlåste handlinger.
☐ Tests dækker timeout, throttling, 5xx, ugyldigt svar, dubletter og genkørsel.
☐ En runbook beskriver afstemning, sikker genkørsel og leverandørkontakt.

Relaterede guides

API-sikkerhed: valider input, svar og misbrugsgrænser SSRF: beskyt udgående URL-kald mod farlige destinationer Baggrundsjob og jobkøer til langsomt arbejde Webhooks: modtag leverandørens hændelser sikkert Logning og overvågning af appen Se hele guidebiblioteket

Officielle kilder

Timeout, retrybare fejl, idempotens og indbyggede retries afhænger af den konkrete leverandør, SDK-version og runtime. Brug principperne her til at stille de rigtige spørgsmål, og kontrollér derefter den aktuelle dokumentation til hver integration.

Virker integrationen, men er fejlscenarierne stadig ukendte?

Startklar er til virksomheder med en fungerende AI-bygget app, som skal kunne bruges trygt af medarbejdere eller kunder. Her kan integrationernes timeouts, retries, statusmodel, tests og overvågning blive gennemgået i den stack, appen faktisk bruger.

Se Startklar-forløbet