Foutafhandeling

De Recruitsome API gebruikt standaard HTTP-statuscodes om aan te geven of een verzoek is geslaagd of mislukt. Deze gids helpt je de verschillende foutscenario's te begrijpen en af te handelen.

Formaat van foutresponses

Alle foutresponses volgen een consistente JSON-structuur:

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

Het errors-object is alleen aanwezig bij validatiefouten (422). Sommige endpoints bevatten ook een machineleesbare error-code. Zie Gestructureerde foutcodes hieronder voor meer informatie.

HTTP-statuscodes

Succescodes (2xx)

Clientfoutcodes (4xx)

Serverfoutcodes (5xx)

Veelvoorkomende foutscenario's

Authenticatiefouten

Ontbrekende of ongeldige API sleutel (401)

{
  "message": "Unauthenticated."
}

Je krijgt hetzelfde antwoord als de sleutel ontbreekt, verkeerd is getypt of is ingetrokken.

Oplossing: Voeg een geldige API sleutel toe in de Authorization-header:

Authorization: Bearer YOUR_API_KEY

Als de header al is ingesteld, controleer dan of de sleutel correct is en niet is ingetrokken via Instellingen → API Sleutels.

Onvoldoende rechten

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 sleutel aan met de vereiste scope via Instellingen → API Sleutels, of vraag je beheerder dit te doen.

Beschikbare scopes:

Validatiefouten

Ongeldige queryparameters (422)

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

Oplossing: Controleer het errors-object voor specifieke veldproblemen.

Ongeldige filterwaarden (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "location_id": ["The selected location id is invalid."]
  }
}

Canonieke URL-host niet toegestaan (422)

POST /vacancies/{slug}/canonical-url accepteert alleen URL's op het domein van je eigen carrièrewebsite:

{
  "message": "The given data was invalid.",
  "errors": {
    "url": ["The URL host must match your configured career website domain."]
  }
}

Oplossing: Geef de URL op precies zoals deze op je carrièrewebsite verschijnt. De host moet overeenkomen met de carrièrewebsite-URL die in Recruitsome is ingesteld (of een van je eigen domeinen).

Resourcefouten

Resource niet gevonden (404)

{
  "message": "Resource not found."
}

Mogelijke oorzaken:

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

Rate limiting

Rate limit overschreden (429)

{
  "message": "Too Many Attempts."
}

Response-headers:

Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705765200

Oplossing: Wacht het aantal seconden in Retry-After (of tot het tijdstip in X-RateLimit-Reset), of implementeer exponential backoff.

Gestructureerde foutcodes

Sommige write-endpoints retourneren naast het bericht een machineleesbare error-code. Zo kan je integratie op basis van de oorzaak vertakken in plaats van tekst te parsen:

Vacancy Closed (400)

POST /applications wanneer de vacature geen sollicitaties meer accepteert:

{
  "message": "This vacancy is no longer accepting applications",
  "error": "VACANCY_CLOSED"
}

Vacancy Not Found (404)

POST /applications wanneer de vacature niet bestaat of niet gepubliceerd is:

{
  "message": "Vacancy not found",
  "error": "VACANCY_NOT_FOUND"
}

Processing Failed (500)

POST /candidates wanneer het cv niet verwerkt kon worden:

{
  "message": "An unexpected error occurred while processing the resume.",
  "error": "PROCESSING_FAILED"
}

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();
}

Debugtips

1. Valideer JSON: Zorg ervoor dat request bodies geldige JSON bevatten
2. Test met cURL: Isoleer problemen door te testen met eenvoudige cURL-commando's
3. Controleer de headers: De rate limit headers vertellen je precies hoeveel ruimte je nog hebt

Hulp nodig?

Als je aanhoudende fouten tegenkomt, neem dan contact op met [email protected]. Vermeld daarbij:

• De naam van je API sleutel (niet de sleutel zelf)
• Requestgegevens (endpoint, parameters)
• De volledige foutmelding en statuscode