Stabiele redencode
Een stabiele foutcode wordt gebruikt in clientlogica, rapportage en automatische routering van aanvragen.
Documentatie / API-fouten
Afhandeling van API-fouten
Een uniform model voor responses, foutcodes, tijdelijke storingen, onbekende uitkomsten, diagnostiek en veilig herstel voor iGaming-integraties.
HTTP
resultaat van het verzoek
Codes
duidelijke reden
Opnieuw proberen
veilige actie
Trace
diagnostiek van verzoeken
Cyclus voor foutafhandeling
Van API-response tot herstel
01
Type resultaat bepalen
Controleer de HTTP-status, redencode, foutcategorie en status van de bewerking.
02
Gegevens voor onderzoek opslaan
Leg de verzoek- en bewerkings-ID's, endpoint, tijd, providerreferentie en veilige parameters vast.
03
Een veilige actie kiezen
Corrigeer de gegevens, stop de bewerking, probeer na een pauze opnieuw of controleer de huidige status.
04
Herstellen en controleren
Voorkom duplicaten, voer reconciliatie uit, waarschuw verantwoordelijke teams en sluit de hoofdoorzaak af.
Overzicht
Een fout moet de oorzaak en de volgende actie uitleggen
Alleen een HTTP 400- of 500-response is niet voldoende. Een betrouwbare API retourneert een stabiele redencode, koppelt de response aan een verzoek-ID en maakt duidelijk of gegevens moeten worden gecorrigeerd, de bewerking moet worden gestopt, het verzoek opnieuw moet worden geprobeerd of de status afzonderlijk moet worden gecontroleerd.
Voorspelbare actie
De foutcategorie geeft aan of het verzoek opnieuw kan worden geprobeerd en welke gegevens moeten worden gewijzigd.
Diagnostische correlatie
Verzoek-, bewerkings- en provider-ID's koppelen clientlogs aan interne systemen en support.
Foutstructuur
Aanbevolen structuur van een foutresponse
De response moet compact, stabiel en geschikt zijn voor geautomatiseerde verwerking zonder interne implementatiedetails of gevoelige gegevens bloot te leggen.
Foutcode
Een stabiele identificatie van de reden die niet verandert wanneer de verklarende tekst wordt aangepast.
Beschrijving
Een korte, veilige uitleg zonder interne code, databasequeries, geheimen of onnodige details.
Verzoek-ID
Een unieke identificatie om de bewerking in logs terug te vinden en contact op te nemen met support.
Aanvullende gegevens
Een toegestane status, limiet, huidige toestand of veilige reden voor afwijzing.
Opnieuw te proberen
Een expliciete aanduiding van een tijdelijke fout die de bescherming tegen duplicaten van de bewerking niet opheft.
Pauze voor nieuwe poging
Een aanbevolen vertraging in seconden of een HTTP-header voor rate limiting en tijdelijke onbeschikbaarheid.
Veldfouten
Een lijst met probleemvelden met redencode, pad naar de waarde en een veilige toelichting.
Verwijzing naar documentatie
Een permanente link of sectie-ID met een beschrijving van de oorzaak en hoe deze kan worden opgelost.
Foutcategorieën
Belangrijkste foutcategorieën
De HTTP-status geeft de algemene resultaatklasse aan, terwijl de interne code de specifieke oorzaak en toegestane actie vastlegt.
Validatiefout in invoer
Ongeldig formaat, een ontbrekend verplicht veld, een niet-ondersteunde waarde, onjuiste precisie van het bedrag of een ongeldige verzoekstructuur.
Authenticatiefout
Een ontbrekende, verlopen of ongeldige token, API-sleutel, signature, tijdstempel van het verzoek of nonce.
Onvoldoende rechten
De client wordt herkend, maar heeft niet de vereiste rol, het merk, de markt of toestemming voor de actie.
Object niet gevonden
Een speler, betaling, ronde, KYC-controle, provider of ander object bestaat niet of is niet beschikbaar voor de client.
Statusconflict
De versie of status van het object is gewijzigd, of de bewerkings-ID is al met andere parameters gebruikt.
Schending van een bedrijfsregel
Onvoldoende saldo, overschreden limiet, geblokkeerde speler, verboden markt of ongeldige statusovergang.
Te veel verzoeken
Het toegestane aantal verzoeken voor de client, methode, rol of kritieke bewerking is overschreden.
Provider niet beschikbaar
De externe dienst is niet beschikbaar, reageert traag of accepteert tijdelijk geen bewerkingen.
Interne fout
Een onverwachte platformfout zonder interne details bloot te leggen, maar met een ID voor diagnostiek.
Opnieuw proberen en herstel
Opnieuw proberen en onbekend resultaat
Opnieuw proberen is alleen veilig nadat het fouttype is vastgesteld en is gecontroleerd of de oorspronkelijke bewerking mogelijk al is voltooid.
01
Controleren of opnieuw proberen is toegestaan
Fouten in gegevens, rechten en bedrijfsregels vereisen doorgaans correctie van het verzoek in plaats van opnieuw verzenden.
02
Dezelfde bewerkingssleutel behouden
Het opnieuw proberen van een financiële, gaming- of andere kritieke bewerking mag geen nieuw resultaat creëren.
03
Pauze tussen pogingen vergroten
Intervallen worden geleidelijk langer, houden rekening met de door de server opgegeven wachttijd en beperken het totale aantal pogingen.
04
Stoppen en escaleren voor beoordeling
Nadat alle pogingen zijn verbruikt, wordt de bewerking als onvoltooid geregistreerd en doorgestuurd voor handmatige controle of reconciliatie.
Geen response betekent niet dat de bewerking is mislukt
Als de verbinding wegvalt nadat een verzoek is verzonden, kan het resultaat onbekend blijven. Controleer vóór een nieuwe poging de status via de bewerkings-ID of wacht op een betrouwbare melding.
Diagnostiek en controle
Logs, identificaties, metrics en waarschuwingen
Diagnostiek moet het verzoekpad tussen platform, adapter en externe provider kunnen reconstrueren zonder onnodige gevoelige gegevens op te slaan.
Context voor onderzoek
Verzoek-, correlatie-, bewerkings- en externe provider-ID's.
Endpoint, HTTP-methode, omgeving, client, tijd en responsduur.
HTTP-status, foutcode, aantal pogingen en eindstatus.
Gemaskerde gevoelige velden, veilige headers en resultaat van signature-validatie.
Monitoring en waarschuwingen
Foutpercentage per methode, provider, client en redencategorie.
Toename van trage responses, HTTP 5xx-fouten, ongeldige signatures en rate-limit-events.
Aantal nieuwe pogingen, bewerkingen met onbekende uitkomst en hersteltaken.
Waarschuwingen met drempels, eigenaren en escalatieregels.
Testen
Wat te testen in de testomgeving
De testomgeving moet elke belangrijke foutcategorie kunnen reproduceren en correct gedrag van client, nieuwe pogingen en controles bevestigen.
Validatiefouten in invoer
Ontbrekende velden, ongeldige typen, niet-ondersteunde waarden, precisie van bedragen en meerdere gelijktijdige fouten.
Toegang en rechten
Ongeldige sleutel, verlopen token, onjuiste signature, onbevoegde rol, geblokkeerd IP en hergebruikte nonce.
Geen response en onbekend resultaat
Verbindingsfout vóór verzending, nadat de bewerking is geaccepteerd en tijdens het ontvangen van de definitieve response.
Rate limiting
HTTP 429, aanbevolen wachttijd, gelijktijdige verzoeken en herstel nadat de beperking is verstreken.
Providerfouten
Onbeschikbaarheid, onderhoud, ongeldige response, vertraagde melding en tegenstrijdige status.
Opnieuw proberen en beschermende stop
Het aantal pogingen beperken, wachttijden vergroten, verzoeken tijdelijk stoppen, gecontroleerd herstel en handmatige escalatie.
Checklist vóór lancering
Een productie-integratie wordt gelanceerd nadat de foutstructuur, het clientgedrag, de bescherming tegen duplicaten en de diagnostiek zijn gevalideerd.
Alle fouten retourneren een stabiele redencode en verzoek-ID.
Foutdetails stellen geen geheimen of interne implementatie bloot.
Tijdelijke en permanente foutcategorieën zijn gedocumenteerd.
Een opnieuw uitgevoerde kritieke bewerking gebruikt dezelfde idempotentiesleutel.
Een onbekend resultaat wordt afgehandeld door de status te controleren of een betrouwbare melding te ontvangen.
Logs, metrics, waarschuwingen, een herstelwachtrij en escalatieregels zijn geconfigureerd.
API-fouten standaardiseren?
Stuur ons uw huidige HTTP-responses, foutcodes, regels voor nieuwe pogingen en probleemsituaties. APIACE helpt een uniform foutmodel, veilig herstel en een controleaanpak te definiëren.