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: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.
customerNameoftitlebij het aanmaken van een lead) - Een veldwaarde voldoet niet aan de regels (bijv. een veld dat te lang is)
- Lees het
message-veld van de response — het beschrijft welk veld het probleem veroorzaakt - Valideer verplichte velden aan clientzijde voordat je ze verstuurt
- Raadpleeg de endpoint-documentatie voor de veldvereisten
401 — Unauthorized (Niet Geauthenticeerd)
Oorzaken:- De
X-API-Keyheader ontbreekt in het verzoek - De API-sleutel is ongeldig of is ingetrokken
- Zorg dat je de header meestuurt:
- Controleer of de sleutel niet is ingetrokken in Instellingen > API-sleutels
- 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:writevoor het aanmaken van een lead)
- Controleer welke scope het endpoint vereist (zie Authenticatie)
- Maak een sleutel aan met de juiste scopes, of gebruik een sleutel met de
fullscope
429 — Too Many Requests (Rate Limit)
Oorzaken:- Er zijn te veel verzoeken in korte tijd verstuurd
- Implementeer retry-logica met exponential backoff (zie hieronder)
- Verlaag de frequentie van je verzoeken; poll niet vaker dan nodig
500 — Internal Server Error (Serverfout)
Oorzaken:- Een onverwachte fout in de servertoepassing
- Deze fouten zijn meestal tijdelijk — implementeer retry-logica met exponential backoff
- Wacht enkele seconden en probeer opnieuw
- Houdt het probleem aan, vermeld dan de
X-Request-Idaan het support team
Foutafhandeling in code
JavaScript/TypeScript
Python
Retry-strategie
Implementeer exponential backoff voor 5xx-fouten en 429:Best practices
- Controleer altijd
response.ok— ga er niet vanuit dat elk verzoek slaagt - Lees het
message-veld — bij een 400 vertelt het precies wat er misging - Bewaar
X-Request-Id— onmisbaar voor supportvragen - Exponential backoff — voor 5xx en 429, met jitter
- Stel timeouts in — voorkom dat verzoeken eindeloos blijven hangen
- Gebruik minimale scopes — beperk de impact als een sleutel lekt