Airtable API: Common troubleshooting

401 error: authentication_required

Error meaning
The API key or access token was not present in the request, or it was passed incorrectly.

Troubleshooting steps
Find your API key or access token and add it to your request. There are two options for including your API key or access token in a request: the Authorization header (recommended) or the api_key query parameter. If using the Authorization header method, make sure to use Bearer authentication (rather than basic).

401 error: unauthorized, invalid authentication token

Error meaning
The API key or access token that was provided is invalid.

Troubleshooting steps
Check that the API key or access token you are using is the same as the key you see on your account page.

403 error: invalid_permissions

Error meaning
The API key or access token was passed correctly in the request, but you do not have permission to perform the action in the API request.

Troubleshooting steps
Reach out to a base/workspace owner or creator to have your permission level increased.

403 error: invalid_permissions (field or table operation limits)

Error meaning
There are table or field-level permissions that are prohibiting the operation; this means that the field or table has been configured to limit who can perform this operation.

Troubleshooting steps
Check the fields and table being referenced in your API request. There are likely conflicting field and table editing permissions. Try performing the same operation as the API request, but within the Airtable UI - this should help to identify the specific field(s) that you are unable to edit by process of elimination.

This error can also occur when creating or updating a record and writing a new value to a linked record field. If we are unable to find a matching record in the linked (foreign) table, then we will attempt to create a record in that foreign table and set the primary field to the value given in the API request. That request to create the foreign record will fail if the foreign table is a synced table since it's not possible to create records in a synced table. It will also fail if the foreign table has a formula field as the primary field since it's not possible to write directly to a formula field.

406 error: blocked

Error meaning

The request was blocked for security reasons.

Troubleshooting steps

If you receive HTTP 406 errors from airtable.com or api.airtable.com and believe these are in error, please submit the following form: https://airtable.com/shrCctlNDza2wevpb

422 error: invalid_request_body (unable to parse request body)

Error meaning
Something is wrong with the request body.

Troubleshooting steps
First, check that the request body is valid JSON, and matches the example request body for the desired operation in our API documentation. Also ensure that the Content-Type: application/json header is included if you are making a POST, PUT, or PATCH request.

422 error: invalid_multiple_choice_options

Error meaning
A select field option that does not yet exist in the field was present in the API request body.

Troubleshooting steps
When creating or updating records, if the choice string does not exactly match an existing option, the request will fail with an INVALID_MULTIPLE_CHOICE_OPTIONS error unless the typecast parameter is enabled. If typecast is enabled, a new choice will be created if one does not exactly match. To see an example of how to include the typecast parameter in your request body, visit the API documentation under "Create records".

429 error: too_many_requests

Error meaning
The rate limit of 5 requests per base per second was exceeded. You will need to wait 30 seconds before subsequent requests succeed.

Troubleshooting steps
Add timeouts to the code to ensure that it stays under the rate limit.

500 errors (500, 502, 503, 504)

Error meaning
500 errors indicate that Airtable was unable to process your request.

Troubleshooting steps
These errors can occur when Airtable's services experience downtime. You can check our Status Page to see if there may be a reported incident at the time you received this error. If you receive any 500 error when there is no reported incident or downtime, please contact our Support team.

These are the most common issues that customers run into at the moment.

1. I’m having trouble using the "filterByFormula" parameter - When using the filterByFormula parameter, the formula provided in the request will be evaluated for each record. If the result is not 0, false, "", NaN, [], or #Error!, then the record will be included in the response. This parameter requires a valid Airtable Formula.
   
   The most effective way to troubleshoot formula issues is to add the formula to your table in a new formula field. That way, you can see what each record in your table returns for that formula and ensure that the results are what you are expecting.
   
   2. I can't upload my attachments with the API. The API request is successful, but in the record revision history I can see that the attachment was deleted right after it was uploaded - When uploading attachments via the API, you must provide a URL where the file is publicly accessible (e.g. not password-protected, network-protected, or expired). Check that the URL you are providing links directly to your file and that there are no access restrictions in place.