Error handling

An overview of potential error responses from our API.

This guide outlines how the Onderwijsloket API reports errors, how to interpret them, and what to consider when troubleshooting API requests. Our API uses the standard Directus error format and error codes.

Global Error Codes

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

Error Code	Status	Description
`FAILED_VALIDATION`	400	Validation for the request or item failed.
`FORBIDDEN`	403	You are not allowed to perform the requested action.
`INVALID_TOKEN`	403	The provided token is invalid.
`TOKEN_EXPIRED`	401	The provided token is valid but has expired.
`INVALID_CREDENTIALS`	401	Username/password or access token is incorrect.
`INVALID_IP`	401	The request originates from an IP address not allow-listed.
`INVALID_OTP`	401	The provided one-time password is incorrect.
`INVALID_PAYLOAD`	400	The request body contains invalid data or structure.
`INVALID_QUERY`	400	One or more query parameters are invalid or not supported.
`UNSUPPORTED_MEDIA_TYPE`	415	The payload format or `Content-Type` header is unsupported.
`REQUESTS_EXCEEDED`	429	The client has exceeded the allowed request rate.
`ROUTE_NOT_FOUND`	404	The requested endpoint does not exist.
`SERVICE_UNAVAILABLE`	503	An external service required to process the request is unavailable.
`UNPROCESSABLE_CONTENT`	422	The request attempts an illegal or restricted operation.
`INTERNAL_SERVER_ERROR`	500	Something went wrong on our end.

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

Error Response Structure

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.

Troubleshooting Guidelines

1. Check Authentication

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

2. Validate Query Parameters

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

3. Inspect Permissions

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

4. 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.

5. 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.

When to contact us for support

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.