Go API-foutafhandelingspatronen voor duidelijke, consistente antwoorden

Waarom inconsistente API-fouten cliënten frustreren

Als elk endpoint fouten op een andere manier meldt, verliezen clients het vertrouwen in je API. De ene route retourneert { "error": "not found" }, een andere { "message": "missing" }, en een derde stuurt platte tekst. Zelfs als de betekenis dicht bij elkaar ligt, moet clientcode nu raden wat er gebeurde.

De kosten verschijnen snel. Teams bouwen fragiele parsinglogica en voegen per endpoint speciale gevallen toe. Retries worden riskant omdat de client niet kan onderscheiden of hij het later nog eens moet proberen of dat zijn invoer onjuist is. Supporttickets nemen toe omdat de client slechts een vage melding ziet en je team die niet makkelijk aan een serverlogregel kan koppelen.

Een veelvoorkomend scenario: een mobiele app roept tijdens signup drie endpoints aan. De eerste geeft HTTP 400 met een veldniveau-foutenmap, de tweede geeft HTTP 500 met een stacktrace-string, en de derde geeft HTTP 200 met { "ok": false }. Het app-team levert drie verschillende fouthandlers en je backend-team krijgt nog steeds meldingen als “signup faalt soms” zonder duidelijke aanwijzing waar te beginnen.

Het doel is één voorspelbaar contract. Clients moeten betrouwbaar kunnen lezen wat er gebeurde: of het hun fout is of die van jou, of retry zinnig is, en een request ID die ze in support kunnen plakken.

Scope-opmerking: dit richt zich op JSON HTTP-API's (niet gRPC), maar dezelfde ideeën gelden overal waar je fouten teruggeeft aan andere systemen.

Een eenvoudig doel: één contract dat elk endpoint volgt

Kies één helder contract voor fouten en zorg dat elk endpoint zich eraan houdt. “Consistent” betekent dezelfde JSON-structuur, dezelfde betekenis van velden en hetzelfde gedrag ongeacht welke handler faalt. Zodra je dat hebt, stoppen clients met raden en beginnen ze fouten af te handelen.

Een nuttig contract helpt clients beslissen wat ze daarna moeten doen. Voor de meeste apps zou elke foutresponse drie vragen moeten beantwoorden:

• Kan ik mijn invoer repareren?
• Moet ik het later opnieuw proberen?
• Moet ik contact opnemen met support?

Een praktische set regels:

• Één response-schema voor alle fouten.
• Eén statuscode-beleid (hetzelfde fouttype wordt altijd naar dezelfde HTTP-status gemapt).
• Eén beleid voor veilige berichten (wat gebruikers mogen zien vs wat intern blijft).
• Eén correlatiehaak (een request ID dat teruggegeven wordt zodat support de fout kan vinden).

Bepaal vooraf wat nooit in responses mag verschijnen. Veelvoorkomende “nooit”-items zijn SQL-fragmenten, stacktraces, interne hostnames, geheimen en ruwe foutstrings van afhankelijkheden.

Houd een duidelijke scheiding: een korte gebruiksgerichte boodschap (veilig, beleefd, actiegericht) en interne details (volledige fout, stack en context) die in logs blijven. Bijvoorbeeld: “We konden je wijzigingen niet opslaan. Probeer het opnieuw.” is veilig. “pq: duplicate key value violates unique constraint users_email_key” is dat niet.

Als elk endpoint hetzelfde contract volgt, kunnen clients één fouthandler bouwen en die overal hergebruiken.

Definieer een foutresponse-schema waarop clients kunnen vertrouwen

Clients kunnen alleen netjes met fouten omgaan als elk endpoint hetzelfde antwoordvorm heeft. Kies één JSON-envelope en houd die stabiel.

Een praktisch standaard is een error-object plus een top-level request_id:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields are invalid.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  },
  "request_id": "req_01HV..."
}

De HTTP-status geeft de brede categorie (400, 401, 409, 500). De machineleesbare error.code geeft het specifieke geval waarop de client kan takken. Die scheiding is belangrijk omdat veel verschillende problemen dezelfde status delen. Een mobiele app kan bijvoorbeeld andere UI tonen voor EMAIL_TAKEN vs WEAK_PASSWORD, ook al zijn beide 400.

Houd error.message veilig en menselijk. Het moet de gebruiker helpen het probleem op te lossen, maar nooit internheden lekken (SQL, stacktraces, provider-namen, bestands- of padnamen).

Optionele velden zijn nuttig als ze voorspelbaar blijven:

• Validatiefouten: details.fields als een map van veld naar bericht.
• Rate limits of tijdelijke problemen: details.retry_after_seconds.
• Extra aanwijzingen: details.docs_hint als platte tekst (geen URL).

Voor backwards compatibility behandel je error.code-waarden als onderdeel van je API-contract. Voeg nieuwe codes toe zonder oude betekenissen te wijzigen. Voeg alleen optionele velden toe en ga ervan uit dat clients velden die ze niet herkennen negeren.

Getypeerde fouten in Go: een helder model voor je handlers

Foutafhandeling wordt rommelig wanneer elke handler zijn eigen manier verzint om falen te signaleren. Een kleine set getypeerde fouten lost dat op: handlers retourneren bekende fouttypes en één response-laag zet die om in consistente responses.

Een praktisch startsetje dekt de meeste endpoints:

• ValidationError (ongeldige invoer)
• NotFoundError (resource ontbreekt)
• ConflictError (unique constraint, state mismatch)
• UnauthorizedError (niet ingelogd of geen permissie)
• InternalError (alles anders)

Het belangrijkste is stabiliteit aan de bovenkant, zelfs als de onderliggende oorzaak verandert. Je kunt lagere niveau-fouten (SQL, netwerk, JSON-parsing) wrappen en toch hetzelfde publieke type teruggeven dat middleware kan detecteren.

type NotFoundError struct {
	Resource string
	ID       string
	Err      error // private cause
}

func (e NotFoundError) Error() string { return "not found" }
func (e NotFoundError) Unwrap() error { return e.Err }

In je handler retourneer je NotFoundError{Resource: "user", ID: id, Err: err} in plaats van sql.ErrNoRows direct te lekken.

Om fouten te controleren, geef de voorkeur aan errors.As voor custom types en errors.Is voor sentinel-fouten. Sentinel-fouten (zoals var ErrUnauthorized = errors.New("unauthorized")) werken voor eenvoudige gevallen, maar custom types winnen wanneer je veilige context nodig hebt (bijvoorbeeld welke resource ontbrak) zonder je publieke response-contract te veranderen.

Wees strikt over wat je toevoegt:

• Publiek (veilig voor clients): een kort bericht, een stabiele code en soms een veldnaam voor validatie.
• Privé (alleen logs): onderliggende Err, stackinfo, ruwe SQL-fouten, tokens, user data.

Die scheiding laat je clients helpen zonder internheden bloot te geven.

Map fouttypes consequent naar HTTP-statuscodes

Als je getypeerde fouten hebt, is de volgende klus saai maar essentieel: hetzelfde fouttype moet altijd dezelfde HTTP-status opleveren. Clients bouwen logica rondom die verwachting.

Een praktische mapping die voor de meeste API's werkt:

Twee onderscheidingen voorkomen veel verwarring:

• 400 vs 422: gebruik 400 wanneer je het verzoek niet betrouwbaar kunt interpreteren (slechte JSON, verkeerde types). Gebruik 422 wanneer je het wél kunt parsen, maar de waarden niet acceptabel zijn.
• 409 vs 422: gebruik 422 voor veldniveau-validatie (wachtwoord te kort). Gebruik 409 wanneer de data valide is maar niet toepasbaar vanwege staat (e-mailadres al in gebruik, order al verzonden, optimistic lock failure).

Retry-richtlijnen zijn belangrijk:

• Meestal veilig om te retry-en: 503, en soms 429 (na wachten).
• Meestal niet veilig om te retry-en zonder wijzigingen: 400, 401, 403, 404, 409, 422.
• Als de operatie idempotent is (PUT met dezelfde body, of POST met idempotency key), worden retries veiliger, zelfs na transitieve fouten.

Request IDs: de snelste manier om clientproblemen te debuggen

Een request ID is een korte unieke waarde die één API-aanroep end-to-end identificeert. Als clients die in elke response kunnen zien, wordt support simpel: “Stuur me de request ID” is vaak genoeg om precies de logs en de fout te vinden.

Deze gewoonte betaalt zich uit bij zowel successes als errors.

Generatie- en propagatieregels

Gebruik één duidelijke regel: als de client een request ID stuurt, behoud die. Zo niet, genereer er dan één.

• Accepteer een inkomende ID via één headernaam (kies er één en documenteer het, bijvoorbeeld X-Request-Id).
• Als de header ontbreekt of leeg is, genereer je een nieuwe ID aan de rand (middleware) en hang je die aan de request-context.
• Verander de ID nooit halverwege het request. Geef hem door aan downstream-aanroepen (DB, andere services) via context of headers.

Plaats de request ID op drie plekken:

• Response header (dezelfde headernaam die je accepteert)
• Response body (als request_id in je standaardschema)
• Logs (als een gestructureerd veld op elke logregel)

Batch- en async-werk

Voor batch-endpoints of background-jobs houd je een parent request ID. Voorbeeld: een client uploadt 200 rijen, 12 falen validatie en je zet werk in de wachtrij. Retourneer één request_id voor de hele call en voeg een parent_request_id toe aan elk job en elk per-item error. Zo kun je één upload tracen, ook als die ontvouwt in veel taken.

Loggen en metrics zonder internals te lekken

Clients hebben een duidelijk, stabiel foutantwoord nodig. Je logs hebben de rommelige waarheid nodig. Houd die twee werelden gescheiden: geef de client een veilig bericht en een publieke foutcode, terwijl je de interne oorzaak, stack en context op de server logt.

Log één gestructureerd event voor elke foutresponse, doorzoekbaar op request_id.

Velden die het waard zijn om consistent te houden:

• request_id
• user_id of account_id (wanneer geauthenticeerd)
• publieke foutcode en HTTP-status
• handler/route-naam en methode
• interne foutdetails (gewrapte oorzaak, validatieveldfouten, upstream timeout)

Bewaar interne details alleen in serverlogs (of in een interne error store). De client mag nooit ruwe databasefouten, querytekst, stacktraces of providerberichten zien. Als je meerdere services runt, kan een intern veld als source (api, db, auth, upstream) het triageproces versnellen.

Houd lawaaiige endpoints en rate-limited fouten in de gaten. Als een endpoint dezelfde 429 of 400 duizenden keren per minuut kan genereren, vermijd logspam: sample herhaalde events of verlaag severity voor verwachte fouten, terwijl je ze nog steeds in metrics meet.

Metrics vangen problemen vroeger dan logs. Meet aantallen gegroepeerd op HTTP-status en foutcode, en stel alerts in bij plotselinge pieken. Als RATE_LIMITED 10x stijgt na een deploy, zie je het snel ook al zijn logs gesampled.

Stapsgewijs: implementeer een consistent foutpipeline in Go

De makkelijkste manier om fouten consistent te maken is te stoppen met ze overal “afhandelen” en ze door één kleine pipeline te leiden. Die pipeline beslist wat de client ziet en wat je voor logs bewaart.

De pipeline in 5 praktische stappen

Begin met een kleine set foutcodes waar clients op kunnen vertrouwen (bijvoorbeeld: INVALID_ARGUMENT, NOT_FOUND, UNAUTHORIZED, CONFLICT, INTERNAL). Wrap ze in een getypeerde fout die slechts veilige, publieke velden blootlegt (code, veilige boodschap, optionele details zoals welk veld fout is). Houd interne oorzaken privé.

Implementeer vervolgens één vertalerfunctie die elke error omzet naar (statusCode, responseBody). Hier mappen getypeerde fouten naar HTTP-statuscodes, en onbekende fouten worden een veilige 500-response.

Voeg daarna middleware toe die:

• ervoor zorgt dat elke request een request_id heeft
• recover van panics

Een panic zou nooit stacktraces naar de client mogen dumpen. Geef een normale 500-response terug met een generiek bericht en log de volledige panic met dezelfde request_id.

Verander ten slotte je handlers zodat ze een error teruggeven in plaats van direct de response te schrijven. Eén wrapper kan de handler aanroepen, de vertaler uitvoeren en JSON in het standaardformaat schrijven.

Een compact checklist:

• Definieer getypeerde fouten met veilige velden en stabiele codes.
• Vertaal fouten naar statuscodes en response-JSON op één plek.
• Voeg request ID- en panic-recovery-middleware toe.
• Laat handlers errors retourneren, niet responses schrijven.
• Voeg golden tests toe voor de vertaler en de wrapper.

Golden tests zijn belangrijk omdat ze het contract vergrendelen. Als iemand later een bericht of statuscode verandert, falen tests voordat clients verrast worden.

Voorbeeld: één endpoint, drie fouten, voorspelbare responses

Stel je één endpoint voor: een client maakt een customer-record aan.

POST /v1/customers met JSON zoals { "email": "[email protected]", "name": "Pat" }. De server retourneert altijd dezelfde foutvorm en altijd een request_id.

1) Validatiefout (400)

Het e-mailadres ontbreekt of is verkeerd geformatteerd. De client kan het veld markeren.

{
  "request_id": "req_01HV9N2K6Q7A3W1J9K8B",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Some fields need attention.",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    }
  }
}

2) Conflict (409)

Het e-mailadres bestaat al. De client kan voorstellen om in te loggen of een ander e-mailadres te kiezen.

{
  "request_id": "req_01HV9N3C2D0F0M3Q7Z9R",
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A customer with this email already exists."
  }
}

3) Transiënte fout (503)

Een dependency is down. De client kan na backoff opnieuw proberen en een rustige melding tonen.

{
  "request_id": "req_01HV9N3X8P2J7T4N6C1D",
  "error": {
    "code": "TEMPORARILY_UNAVAILABLE",
    "message": "We could not save your request right now. Please try again."
  }
}

Met één contract reageert de client consistent:

• 400: markeer velden met details.fields
• 409: leid de gebruiker naar een veilige volgende stap
• 503: vraag om retry en toon de request_id als support-ID

Voor support is diezelfde request_id de snelste weg naar de echte oorzaak in interne logs, zonder stacktraces of databasefouten bloot te geven.

Veelvoorkomende valkuilen die foutafhandeling erger maken

De snelste manier om API-clients te irriteren is ze te laten raden. Als het ene endpoint { "error": "..." } retourneert en een ander { "message": "..." }, verandert elke client in een stapel speciale gevallen en verstoppen bugs zich wekenlang.

Een paar veelgemaakte fouten:

• HTTP 200 teruggeven met een fout in de body, of wisselen tussen meerdere foutschema's over endpoints heen.
• Internals tonen in het gebruikersbericht, zoals SQL-fouten, stacktraces, IP's, afhankelijkheids-hostnames of bestandsnamen.
• Menselijke tekst als enige identifier gebruiken in plaats van een stabiele code waar clients op kunnen keyen.
• Foutcodes zomaar wijzigen (of dezelfde code voor verschillende problemen hergebruiken) en clients breken die voor het oude gedrag geschreven zijn.
• request_id alleen bij failures toevoegen, zodat je een gebruikersmelding niet kunt correleren met de succesvolle call die een later probleem triggerde.

Internals lekken is de makkelijkste valkuil. Een handler retourneert err.Error() omdat het handig is, en ineens staat een constraintnaam of derdepartijmelding in productionresponses. Houd het clientbericht veilig en kort, en zet de gedetailleerde oorzaak in logs.

Vertrouwen op tekst alleen is een andere sluipmoordenaar. Als de client Engelse zinnen moet parsen zoals “email already exists”, kun je de tekst niet veranderen zonder logica te breken. Stabiele foutcodes laten je berichten aanpassen, vertalen en toch consistent gedrag behouden.

Behandel foutcodes als onderdeel van je publieke contract. Als je er één moet veranderen, voeg dan een nieuwe code toe en houd de oude code nog even werkend, ook als beide naar dezelfde HTTP-status mappen.

Tot slot: voeg hetzelfde request_id-veld toe aan elke response, succes of fout. Als een gebruiker zegt “het werkte, daarna brak het”, redt die ene ID vaak een uur zoekwerk.

Snelle checklist voordat je live gaat

Voordat je releaset, doe een snelle controle op consistentie:

• Eén foutvorm overal. Elk endpoint retourneert dezelfde JSON-velden (bijvoorbeeld: error.code, error.message, request_id).
• Stabiele foutcodes met dekking. Houd codes kort en saai (VALIDATION_FAILED, NOT_FOUND, CONFLICT, UNAUTHORIZED). Voeg tests toe zodat handlers niet per ongeluk onbekende codes teruggeven.
• Één status-mapping regelboek. Bepaal hoe elk fouttype naar een HTTP-status mapt en pas dat centraal toe.
• Request ID in beide richtingen. Retourneer altijd een request_id en log hem voor elke request, inclusief panics en timeouts.
• Standaard veilige berichten. Gebruikersmeldingen moeten kort, duidelijk en actiegericht zijn; nooit stacktraces, SQL-fouten of vendor-namen.

Daarna: controleer een paar endpoints handmatig. Trigger een validatiefout, een ontbrekend record en een onverwachte fout. Als responses over endpoints heen verschillen (velden veranderen, statuscodes driften, berichten oversharen), repareer dan de gedeelde pipeline voordat je meer features toevoegt.

Een praktische regel: als een bericht een aanvaller zou helpen of een normale gebruiker in de war brengt, hoort het in logs, niet in de response.

Volgende stappen: standaardiseer nu en houd het later consistent

Schrijf het foutcontract op dat je wilt dat elk endpoint volgt, zelfs als je API al live is. Een gedeeld contract (status, stabiele foutcode, veilig bericht en request_id) is de snelste manier om fouten voorspelbaar te maken voor clients.

Migreer vervolgens geleidelijk. Houd je bestaande handlers, maar leid hun fouten door één mapper die interne fouten naar je publieke responsevorm omzet. Dit verbetert consistentie zonder een risicovolle grote rewrite en voorkomt dat nieuwe endpoints nieuwe formaten uitvinden.

Houd een kleine foutcode-catalogus en behandel die als onderdeel van je API. Als iemand een nieuwe code wil toevoegen, doe een korte review: is het echt nieuw, is de naam duidelijk en mapt het naar de juiste HTTP-status?

Voeg een handvol tests toe die drift detecteren:

• Elke foutresponse bevat request_id.
• Statuscode matcht het fouttype (niet de fouttekst).
• error.code is aanwezig en komt uit de catalogus.
• error.message blijft veilig en bevat nooit interne details.
• Onbekende fouten vallen terug op 500 met een generiek bericht.

Als je een Go-backend vanaf nul bouwt, helpt het om het contract vroeg vast te leggen. Bijvoorbeeld, Koder.ai (koder.ai) bevat een planningsmodus waar je conventies zoals een foutschema en codecatalogus vooraf kunt definiëren en handlers op één lijn kunt houden terwijl de API groeit.