Skip to main content

Foutafhandeling

Deze pagina beschrijft de HTTP statuscodes, het foutrespons-formaat en best practices voor het afhandelen van fouten in de Flixer Pro API.

HTTP Statuscodes

Foutresponse-formaat

Foutresponsen volgen het standaard NestJS-formaat met drie velden:
Velden:
  • statusCode — De HTTP statuscode (komt overeen met de response-status)
  • message — Een mensvriendelijke foutbeschrijving. Bij validatiefouten kan dit een array van strings zijn (één per veld dat niet voldoet)
  • error — De HTTP status-tekst (bijv. Bad Request, Unauthorized)
Elke response bevat ook een X-Request-Id header. Bewaar deze waarde en vermeld hem bij supportvragen — het maakt het mogelijk om het verzoek aan serverkant terug te vinden.

Veelvoorkomende fouten

400 — Bad Request (Validatiefout)

Oorzaken:
  • Een verplicht veld ontbreekt (bijv. customerName of title bij het aanmaken van een lead)
  • Een veldwaarde voldoet niet aan de regels (bijv. een veld dat te lang is)
Oplossingen:
  1. Lees het message-veld van de response — het beschrijft welk veld het probleem veroorzaakt
  2. Valideer verplichte velden aan clientzijde voordat je ze verstuurt
  3. Raadpleeg de endpoint-documentatie voor de veldvereisten

401 — Unauthorized (Niet Geauthenticeerd)

Oorzaken:
  • De X-API-Key header ontbreekt in het verzoek
  • De API-sleutel is ongeldig of is ingetrokken
Oplossingen:
  1. Zorg dat je de header meestuurt:
  2. Controleer of de sleutel niet is ingetrokken in Instellingen > API-sleutels
  3. Maak indien nodig een nieuwe sleutel aan

403 — Forbidden (Onvoldoende Scope)

Oorzaken:
  • De sleutel is geldig, maar mist de scope die dit endpoint vereist (bijv. leads:write voor het aanmaken van een lead)
Oplossingen:
  1. Controleer welke scope het endpoint vereist (zie Authenticatie)
  2. Maak een sleutel aan met de juiste scopes, of gebruik een sleutel met de full scope

429 — Too Many Requests (Rate Limit)

Oorzaken:
  • Er zijn te veel verzoeken in korte tijd verstuurd
Oplossingen:
  1. Implementeer retry-logica met exponential backoff (zie hieronder)
  2. Verlaag de frequentie van je verzoeken; poll niet vaker dan nodig

500 — Internal Server Error (Serverfout)

Oorzaken:
  • Een onverwachte fout in de servertoepassing
Oplossingen:
  1. Deze fouten zijn meestal tijdelijk — implementeer retry-logica met exponential backoff
  2. Wacht enkele seconden en probeer opnieuw
  3. Houdt het probleem aan, vermeld dan de X-Request-Id aan het support team

Foutafhandeling in code

JavaScript/TypeScript

Python

Retry-strategie

Implementeer exponential backoff voor 5xx-fouten en 429:
Herhaal verzoeken alleen wanneer dat veilig is. GET-verzoeken zijn idempotent en altijd veilig te herhalen. Wees voorzichtig met POST /leads: herhaal alleen na een 5xx of een netwerkfout (waarbij de lead waarschijnlijk niet is aangemaakt), niet na een 400/401/403.

Best practices

  1. Controleer altijd response.ok — ga er niet vanuit dat elk verzoek slaagt
  2. Lees het message-veld — bij een 400 vertelt het precies wat er misging
  3. Bewaar X-Request-Id — onmisbaar voor supportvragen
  4. Exponential backoff — voor 5xx en 429, met jitter
  5. Stel timeouts in — voorkom dat verzoeken eindeloos blijven hangen
  6. Gebruik minimale scopes — beperk de impact als een sleutel lekt