Foutafhandeling

De RecruitSome API gebruikt standaard HTTP-responscodes om het slagen of falen van verzoeken aan te geven. Deze handleiding helpt je bij het begrijpen en afhandelen van verschillende foutscenario's.

Formaat van foutresponses

Alle foutresponses volgen een consistente JSON-structuur:

{
  "message": "Human-readable error description",
  "errors": {
    "field_name": ["Specific validation error for this field"]
  }
}

HTTP-statuscodes

Succescodes (2xx)

Code	Beschrijving
200	OK – Verzoek geslaagd
201	Created – Resource succesvol aangemaakt
204	No Content – Verzoek geslaagd zonder responsinhoud

Clientfoutcodes (4xx)

Code	Beschrijving
401	Unauthorized – Ongeldige of ontbrekende API-sleutel
403	Forbidden – Geldige API-sleutel maar onvoldoende rechten
404	Not Found – Resource bestaat niet
422	Unprocessable Entity – Validatiefouten
429	Too Many Requests – Rate limit overschreden

Serverfoutcodes (5xx)

Code	Beschrijving
500	Internal Server Error – Er is iets misgegaan aan onze kant
502	Bad Gateway – Tijdelijk serverprobleem
503	Service Unavailable – API is tijdelijk offline

Veelvoorkomende foutscenario's

Authenticatiefouten

Ontbrekende API key

{
  "message": "Unauthenticated."
}

Oplossing: Voeg je API key toe in de Authorization header:

Authorization: Bearer YOUR_API_KEY

Ongeldige API key

{
  "message": "Invalid authentication credentials."
}

Oplossing: Controleer of je API key correct is en niet is ingetrokken.

Autorisatiefouten

API-toegang uitgeschakeld

{
  "message": "API access is not enabled for this tenant."
}

Oplossing: Neem contact op met je beheerder om API-toegang in te schakelen via Instellingen → Integraties.

Validatiefouten

Ongeldige queryparameters

{
  "message": "The given data was invalid.",
  "errors": {
    "per_page": ["The per page must not be greater than 100."],
    "language": ["The language must be 2 characters."]
  }
}

Oplossing: Controleer het errors-object voor specifieke veldproblemen.

Ongeldige filterwaarden

{
  "message": "The given data was invalid.",
  "errors": {
    "location_id": ["The selected location id is invalid."],
    "job_types.0": ["The job_types.0 must be an integer."]
  }
}

Onvoldoende scope

Ontbrekende API-permissie (403)

{
  "message": "This API key does not have the required permission: candidates:read",
  "error": "INSUFFICIENT_SCOPE",
  "required_scope": "candidates:read"
}

Oplossing: Maak een nieuwe API key aan met de vereiste scope via Instellingen → Integraties → API Keys, of neem contact op met je beheerder. Beschikbare scopes:

Scope	Toegang
vacancies:read	Gepubliceerde vacatures en facetten bekijken
applications:write	Sollicitaties indienen
candidates:read	Kandidatenlijst en profielen bekijken
candidates:write	Kandidaten aanmaken via cv-upload
team:read	Teamleden bekijken
locations:read	Kantoorlocaties bekijken
articles:read	Gepubliceerde artikelen lezen

Resourcefouten

Vacature niet gevonden

{
  "message": "The requested resource was not found."
}

Mogelijke oorzaken:

• Ongeldige slug
• Vacature is niet gepubliceerd
• Vacature is niet beschikbaar via het API-kanaal
• Vacature is verlopen

Rate limiting

Rate limit overschreden

{
  "message": "Too many requests. Please wait before trying again."
}

Response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705765200

Oplossing: Wacht tot de resettijd verstreken is of implementeer exponential backoff.

Best practices voor foutafhandeling

1. Implementeer retry-logica

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        // Rate limited - wait before retry
        const resetTime = response.headers.get('X-RateLimit-Reset');
        const waitTime = resetTime 
          ? (parseInt(resetTime) * 1000) - Date.now()
          : Math.pow(2, i) * 1000; // Exponential backoff
        
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      if (response.status >= 500) {
        // Server error - retry with exponential backoff
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

2. Validatiefouten afhandelen

async function createResource(data) {
  const response = await fetch('/api/v1/resource', {
    method: 'POST',
    headers: {
      'Authorization': Bearer ${API_KEY},
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });
  
  if (response.status === 422) {
    const error = await response.json();
    // Display field-specific errors to user
    Object.entries(error.errors).forEach(([field, messages]) => {
      console.error(${field}: ${messages.join(', ')});
    });
    return null;
  }
  
  return response.json();
}

3. Fouten op de juiste manier loggen

function logApiError(error, context) {
  const errorLog = {
    timestamp: new Date().toISOString(),
    context: context,
    status: error.status,
    message: error.message,
    errors: error.errors,
    requestId: error.headers?.get('X-Request-ID')
  };
  
  // Send to your logging service
  console.error('API Error:', errorLog);
}

Debuggingtips

1. Controleer de response headers: Zoek naar X-Request-ID om te vermelden wanneer u contact opneemt met support
2. Valideer JSON: Zorg ervoor dat request bodies geldige JSON bevatten
3. Controleer de API-status: Bezoek https://status.recruitsome.com voor de servicestatus
4. Test met cURL: Isoleer problemen door te testen met eenvoudige cURL-commando's
5. Schakel debugmodus in: Voeg ?debug=true toe voor meer gedetailleerde foutmeldingen (alleen voor ontwikkeling)

Hulp nodig

Als u aanhoudende fouten tegenkomt:

1. Noteer de foutmelding en statuscode
2. Leg het X-Request-ID uit de response headers vast
3. Neem contact op met [email protected] met:

- De naam van uw API-key (niet de key zelf)

- Requestgegevens (endpoint, parameters)

- Foutrespons

- Request-ID