Error handling

The Onderwijsloket API uses the standard Directus error format and error codes. Use the response code and error payload together to identify the failed part of a request.

Interpret common error codes

The table below lists the error codes you may encounter when interacting with the API.

To avoid leaking information about which items exist, all actions on non-existing items return a FORBIDDEN error rather than NOT_FOUND.

Read the error response

All errors follow the standard Directus error response format:

{
  "errors": [
    {
      "message": "Invalid query parameter.",
      "extensions": {
        "code": "INVALID_QUERY"
      }
    }
  ]
}

Each error object includes a human-readable message and a machine-readable code found under extensions.code.

Troubleshoot a failed request

Check authentication

Ensure that your API token is valid, not expired, and included in the Authorization header.

Validate query parameters

Errors such as INVALID_QUERY or INVALID_PAYLOAD often result from incorrect field names, unsupported operators, or malformed request bodies.

Inspect permissions

A FORBIDDEN response typically indicates insufficient permissions. Verify that the authenticated role has the required access to the collection or item.

Monitor rate limits

Although individual users are not subject to per-user rate limits, the platform enforces global rate limits to protect system stability. If you receive a REQUESTS_EXCEEDED error, lower your request frequency or implement retry logic with exponential backoff.

Confirm endpoint availability

A ROUTE_NOT_FOUND error indicates a typo in the URL or the use of an endpoint not available in the current API version.

Contact support with useful context

If you encounter errors in the 5xx range or errors that persist after verifying your token, permissions, query structure, and rate limits, contact the Onderwijsloket technical team. Include the full error response (excluding sensitive tokens) and the timestamp of the request to help us trace the issue in our monitoring tools.