Intro Documentatie & testen Swagger Terminologie ClientID Access Token Webhooks Postman Problemen oplossen Best practices Datamodel FAQ Releasenotes Use cases


Als softwareontwikkelaar die de Coachview API integreert, is het van cruciaal belang om bekend te zijn met verschillende statuscodes om de interactie met de API soepel te laten verlopen. In dit artikel behandelen we de belangrijke aspecten van problemen die kunnen voorkomen.

Statuscode 401:
Statuscode 401, ook bekend als "401 Unauthorized", is een HTTP-responscode die aangeeft dat de toegang tot de aangevraagde bron is geweigerd vanwege het ontbreken van geldige authenticatiegegevens. Dit betekent dat de server de identiteit van de gebruiker die de aanvraag doet, niet heeft kunnen verifiëren of dat de verstrekte inloggegevens onjuist zijn. Het is alsof je probeert een beveiligde deur te openen zonder de juiste sleutel. 

Wanneer treedt Statuscode 401 op in Coachview?
Wanneer je geen toegang krijgt en de foutmelding 401 ziet, kan dit door een paar verschillende dingen komen:

  1. Ongeldig clientid en/of secret: Het is mogelijk dat het clientid (gebruikersnaam) en/of het secret (wachtwoord) niet klopt. Controleer of je de juiste gegevens hebt ingevoerd en probeer het opnieuw. Hier vind je meer informatie over het onderhouden van clients.
  2. Access token verlopen: Het access token (de sleutel) is verlopen. Vraag een nieuw access token aan en probeer het opnieuw. Hiervind je meer informatie over het aanvragen van een access token.
  3. Client is inactief: Het is mogelijk een cliënt (tijdelijk) op inactief te zetten. Ook dan krijg je een status 401 wanneer je probeert toegang te krijgen tot de API. Ga naar de onderhoudspagina van de clients en controleer de instellingen van de cliënt. Hier vind je meer informatie over het onderhouden van clients.

Statuscode 403:

Statuscode 403, ook bekend als "403 Forbidden", is een HTTP-responscode die aangeeft dat de server het verzoek heeft begrepen, maar weigert het te autoriseren. In de context van de Coachview API betekent dit dat de aanvraag goed is ontvangen, maar de server geen toegang verleent tot de gevraagde bron omdat de gebruiker niet de juiste machtigingen heeft.


Wanneer treedt Statuscode 403 op in Coachview?

Een 403-statuscode treedt vaak op wanneer je interacteert met de Coachview API onder de volgende omstandigheden:

  1. Ga naar de Onderhoudspagina van de Clients: Bezoek Coachview Client Onderhoudspagina om je clientinstellingen te beheren.
  2. Pas de Client Aan: Zoek de betreffende client op en controleer de scopes. Voeg de ontbrekende scopes toe die nodig zijn voor de functionaliteiten die je wilt gebruiken. Dit zorgt ervoor dat je client de juiste toegangsrechten heeft.
  3. Vraag opnieuw een Token aan: Na het aanpassen van de scopes, moet je een nieuw toegangstoken aanvragen. Zorg ervoor dat je bij deze aanvraag de benodigde scopes correct meestuurt. Dit token zal dan de juiste autorisaties bevatten.
  4. Test de API-oproep opnieuw: Na het verkrijgen van het nieuwe token, probeer de eerder gefaalde API-oproep opnieuw uit te voeren. Als alle stappen correct zijn gevolgd, zou de toegang nu geautoriseerd moeten zijn.
Hoe los je statuscode 403 op in Coachview?

Het oplossen van een 403-fout in de Coachview API vereist enkele stappen om te zorgen dat de juiste permissies zijn ingesteld:

  1. Ga naar de Onderhoudspagina van de Clients: Bezoek Coachview Client Onderhoudspagina om je clientinstellingen te beheren.
  2. Pas de Client Aan: Zoek de betreffende client op en controleer de scopes. Voeg de ontbrekende scopes toe die nodig zijn voor de functionaliteiten die je wilt gebruiken. Dit zorgt ervoor dat je client de juiste toegangsrechten heeft.
  3. Vraag opnieuw een Token aan: Na het aanpassen van de scopes, moet je een nieuw toegangstoken aanvragen. Zorg ervoor dat je bij deze aanvraag de benodigde scopes correct meestuurt. Dit token zal dan de juiste autorisaties bevatten.
  4. Test de API-oproep opnieuw: Na het verkrijgen van het nieuwe token, probeer de eerder gefaalde API-oproep opnieuw uit te voeren. Als alle stappen correct zijn gevolgd, zou de toegang nu geautoriseerd moeten zijn.

Statuscode 429:
De HTTP-statuscode 429, bekend als "Too Many Requests" (Te veel verzoeken), wordt gebruikt om aan te geven dat de server tijdelijk de toegang heeft beperkt vanwege een overmatig aantal verzoeken binnen een bepaalde periode. Het is een mechanisme om de server te beschermen tegen overbelasting door herhaalde verzoeken.
Dagelijks Limiet en 429-statuscode in Coachview API
Wanneer je de Coachview API gebruikt, kan de statuscode 429 optreden als het dagelijkse limiet is overschreden. De limiet bedraagt 5.000 requests per 24 uur. Wanneer dit limiet wordt bereikt, zal de server reageren met een 429-statuscode om aan te geven dat verdere verzoeken tijdelijk worden geblokkeerd.
Informatie in de Response Header

Om ontwikkelaars in staat te stellen hun verbruik te monitoren, bevat de HTTP-responseheader enkele belangrijke velden met betrekking tot de limiet:

  1. X-Rate-Limit-Limit: Dit veld geeft het totale aantal toegestane verzoeken aan binnen de opgegeven tijdsperiode (bijvoorbeeld 5000).
  2. X-Rate-Limit-Remaining: Hiermee kun je zien hoeveel verzoeken je nog kunt indienen voordat de limiet wordt bereikt.
  3. X-Rate-Limit-Reset: Dit veld bevat de timestamp waarop de limiet zal worden gereset. Het is essentieel om dit veld te gebruiken om te bepalen wanneer je opnieuw requests kunt indienen.
Wachten op reset van de limiet
Indien de limiet is bereikt (status 429 ontvangen), is het noodzakelijk om te wachten tot het limiet is gereset voordat er nieuwe verzoeken worden ingediend. Door proactief de informatie in de responseheaders te monitoren en de wachttijd te implementeren, voorkom je onnodige blokkades en zorg je voor een optimale interactie met de Coachview API.
Statuscode 429 bij te hoog aantal POST webaanvragen binnen 5 minuten
Indien binnen 5 minuten meer dan 20 webaanvragen aangemaakt worden wordt ook de HTTP-statuscode 429 terug gegeven. Vanwege veiligheidsoverwegingen (bots etc.) is er een maximum van 20 webaanvragen per 5 minuten ingesteld.

Error: Could not complete OAuth 2.0 token request

Het lukt niet om een token aan te vragen. Oplossing: Access Token URL juist instellen

Ben je ingelogd? Klik dan hier.

Error: invalid_client

Er is een clientId ingevuld dat niet bekend is bij Coachview

Oplossing: Controleer het clientId. Géén spaties of andere tekens ervoor/erachter

Krijg je nog steeds de melding? Controleer dan ook het secret.


Error: invalid_scope

Er is een scope opgegeven die niet bestaat

Aandachtspunten:

  • Scopes zijn hoofdletter gevoelig! (Personen.Lezen)
  • Scopes dienen gescheiden te worden met een spatie! (Personen.Lezen Personen.Schrijven)


De meest voorkomende meldingen op een rijtje.
Melding:Oplossing/reden:
HTTP-status code 400 Bad Request. Validatie fout opgetreden.

Voorbeeld
{
"error": [
{
"code": "modelValidation",
"message": "The Achternaam field is required.",
"target": "Achternaam"
}
]		De reden van deze melding is dat de validatie niet juist is.
In de response kun je zien wat de exacte melding is. In het voorbeeld betekent dit dat je de "Achternaam" niet of leeg meegegeven hebt. Zorg ervoor dat dit veld meegegeven wordt.







HTTP-status code 401: Unauthorized
Er is geen token meegegeven of het token is niet meer geldig.

Oauth token opnieuw aanvragen en opnieuw proberen.
HTTP-status code 403: Forbidden
Er zijn geen rechten op de API.		Deze melding kan meerdere oorzaken hebben.
  1. Scope niet aangevraagd of geen rechten op scope.
  2. Niet voldoende rechten in Coachview op deze functie.
  3. Module is niet geactiveerd in Coachview die bij deze API hoort.
HTTP-status code 403: Forbidden bij het versturen van webhook naar Coachview. Bijvoorbeeld bij de generieke koppeling. Wanneer je een webhook naar Coachview stuurt dan is het belangrijk dat je het bericht stuurt in BASE64 formaat. Stuur je het bericht in een ander formaat dan zal Coachview nooit een akkoord geven, omdat de berichten niet overeenkomen. Je krijgt dan de 403 Forbidden code.
HTTP-status code 404
Record wat opgehaald wordt bestaat niet.

--
HTTP-status code 404
POST /api/v1/Bedrijven		Kijk in de melding wat de exacte reden is. Voorbeeld kan zijn dat de landcode die je mee geeft niet bestaat.

HTTP-status code 409
De waarde van "data" is niet geldig. Bijvoorbeeld voor het type van het vrijveld.

--
HTTP-status code 412
Entiteit is in de tussentijd gewijzigd.

--
HTTP-status code 429 (Too Many Requests)Er zijn teveel requests uitgevoerd binnen een bepaalde periode. Neem contact op met support. Hiervoor kun je een ticket indienen.
HTTP-status code 500
Technische foutmelding. In de response staat een nummer.		Neem contact op met support. Hiervoor kun je een ticket indienen met het nummer erbij. Geef daarbij aan welke API gebruikt is, welk tijdstip en of het voor de productie of test-omgeving is.
Postman: Error: Could not complete OAuth 2.0 token request.
Je hebt niet de juiste Access Token URL ingesteld. Voor trainingsomgeving is dat https://training.coachview.net/auth/connect/token en voor live https://secure.coachview.net/auth/connect/token.
Postman: Error: Invalid_clientDe client_id is niet bekend bij Coachview. Controleer het client_id. Geen spaties of andere tekens ervoor of erachter. Controleer ook of secret goed ingevuld is.
Postman: Error: Invalid_scopeDe opgegeven scope bestaat niet. Let op: scopes zijn hoofdlettergevoelig en heb je meerdere scopes dan dient er een spatie tussen de scopes te staan. Daarnaast dient de eerste api er ook bij te staan. Bijvoorbeeld "api Personen.Lezen Personen.Schrijven".
Postman: Error: Invalid_clientDe client_id is niet bekend bij Coachview. Controleer het client_id. Geen spaties of andere tekens ervoor of erachter. Controleer ook of secret goed ingevuld is.
Connection reset by peerHet is mogelijk om API's met een script aan te roepen en op die manier automatisch gegevens op te halen. Een stap die altijd nodig is in het script is het maken van een connectie. Je kunt een connectie op meerdere manieren gebruiken. Je kunt namelijk iedere keer wanneer je een request doet de connectie maken of je maakt één keer een connectie en vervolgens hergebruik je die connectie. Gebruik je de eerste methode, dus je maakt 50 keer een connectie, dan kan het zijn dat de connectie niet goed afgesloten wordt en open blijft staan. Wanneer dit teveel gebeurt, dan komt deze melding. Oplossing is één connectie aanmaken en deze hergebruiken bij de andere requests.
Fout bij aanmaken Client ID. Wordt op de link geklikt dan wordt foutmelding '403 forbidden' teruggestuurd, terwijl je wel in de Coachview omgeving bent ingelogd. Wordt op 'client toevoegen' geklikt? Dan verschijnt er een pop-up die opent en direct sluit.Aan het gebruikersaccount waarmee in Coachview ingelogd wordt zijn geen administrator rechten toegekend. In het gebruikersaccount moet de rol 'Administrator' worden toegevoegd.


Bijgewerkt tot en met versie 90