Onderwijsregio APIGuideAPI ReferenceChangelog
Status

Troubleshooting

This section describes known issues and recommended workarounds when integrating with the API.

Why not provide direct access to the Airtable API?

We intentionally do not provide direct access to the underlying Airtable API.

The primary reason is data separation. The Airtable base is shared across multiple education regions, and direct access would make it possible to view or modify data belonging to other regions, which is not acceptable from a privacy and governance perspective.

Additionally, the Airtable setup relies on strict internal conventions and constraints. While Airtable’s flexibility is a strength, it also makes it easy to unintentionally break data structures or workflows. The API layer acts as a controlled abstraction, enforcing validation and business logic to protect data integrity and system stability across all regions.

Rate limits

The Airtable API enforces strict rate limits—no more than 5 requests per second, shared across all regions.

What this means in practice

  • Mutations (create/update/delete)
    These are handled by the mutation engine, which abstracts away rate-limit concerns for write operations.

  • GET requests
    Rate limits do apply to all read endpoints. If you issue many GET requests in quick succession, you may encounter (rate-limit) errors.

Important
If you start seeing (rate-limit) errors while making GET requests, implement a backoff strategy (for example, exponential backoff with retries) to stay within Airtable’s limits.

These errors might not always be 429, they could also occur as 500 responses.

Recommended approach

  • Batch or cache read requests where possible

  • Avoid tight request loops

  • Add retry logic with increasing delays when rate-limit errors occur

Need help?

If you encounter issues or unexpected behavior, feel free to get in touch. We are happy to help troubleshoot and assist with your integration.