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.

Understand the impact

• Mutations (create, update, and delete): The Mutation Engine handles write-operation rate limiting.
• GET requests: Rate limits apply to every read endpoint. A high volume of requests in quick succession can cause rate-limit errors.

Use a resilient read strategy

• 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 /schema request for a region can be slow. Airtable performs database introspection to determine the region-specific schema. Later requests use a cached response and are typically much faster.

Field schemas are cached for 72 hours.

The same applies when you submit a candidate with customFields. The API must inspect your region’s schema before validating that payload.

Read the schema guide for the shared candidate data model and region-specific custom fields.

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.

The Mutation Engine cannot avoid this delay for POST requests because validation happens before a mutation is queued.

Read the Mutation Engine guide to understand how write operations are processed.

403 vs. 404 errors

For some lookups and record-ID operations, Airtable returns 403 when a record cannot be found.

This can happen in these routes:

• [GET/PATCH/DELETE] /api/v2/candidates/:id/interactions/:interactionId when interactionId does not exist in your region’s database.
• [POST/PATCH/DELETE] /api/v2/candidates/:id when the candidate record cannot be found.

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.

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