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.

Recommended approach

• Batch or cache read requests where possible

• Avoid tight request loops

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

Performance considerations for schema introspection

The first time you request the /schema endpoint for a given region, you should expect a latency. During this initial request, Airtable performs database introspection to determine the region-specific schema, which is inherently slow. Subsequent requests return a cached response and are typically served much faster.

This is also true when you are submitting a candidate with customFields. In this case we need to validate the custom fields payload, and therefore internally perform schema introspection for your region.

Schema

The schema provides a complete overview of the shared candidate data model and the region-specific custom fields that apply to your education region.

If our system does not hit a valid cache entry, this introspection will take approximately 3 - 5 seconds, which will directly affect the response time for your request.

This is not a problem we can solve with the Mutation Engine (for POST requests), since validation happens before a mutation in enqueued.

Mutation Engine

The Mutation Engine is the system responsible for all write operations in our API.

403 vs. 404 errors

In certain scenario’s, specifically when a lookup or operation by record id is performed, Airtable will throw a 403 error if the record is not found.

This can happen in these routes:

• [GET/PATCH/DELETE] /api/v2/candidates/:id/interactions/:interactionId, if the provided interactionId does not exist in your regions' database.

• [POST/PATCH/DELET] /api/v2/candidates/:id if the

Attachment uploads may fail silently

Attachment uploads are processed asynchronously by Airtable. As a result, a mutation may succeed even if one or more attachments fail to upload.

In these cases, Airtable may either remove the attachment from the record or store it with a URL that later returns an error. Only after repeated failures may Airtable return an explicit ATTACHMENTS_FAILED_UPLOADING error.

What this means: a successful mutation response does not guarantee that all attachments were stored correctly. This is a limitation of Airtable and cannot be detected by the Mutation Engine.

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.