Airtable API: Common troubleshooting
  • 07 Mar 2024
  • 8 Minutes to read
  • Dark
    Light
  • PDF

Airtable API: Common troubleshooting

  • Dark
    Light
  • PDF

Article Summary

At times, you may encounter errors while making API calls. This article is meant to explain and troubleshoot the most common errors or issues that folks run into. For an exhaustive listing of errors please refer to our API documentation. If you end up needing to send in a support ticket, please follow the guidelines listed in the last section to have the most efficient customer service experience.

2xx codes signify success, 4xx mostly represent user error, 5xx generally correspond to a server error. The error messages will return a JSON-encoded body that contains error and message fields. Those will provide specific error conditions and human-readable messages to identify what caused the error.

Success code

200 OK - Request completed successfully.

User error codes

These errors generally indicate a problem on the client side. If you are getting one of these, check your code and the request details.

  • 400 Bad Request - The request encoding is invalid; the request can't be parsed as a valid JSON.

  • 401 Unauthorized - Accessing a protected resource without authorization or with invalid credentials.

    • 401 error: authentication_required

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

      • Troubleshooting steps - Find your access token and add it to your request. To include an access token in the request use the Authorization header. When using the Authorization header method, make sure to use Bearer authentication (rather than basic).

    • 401 error: unauthorized, invalid authentication token

      • Error meaning - The access token that was provided is invalid.

      • Troubleshooting steps - Check that the access token you are using is the same as the access token you’ve already set up.

  • 403 Forbidden - Accessing a protected resource with API credentials that don't have access to that resource. See below for examples and suggested debugging steps.

    • 403 error: invalid_permissions

      • Error meaning - The 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.

  • 404 Not Found - Route or resource is not found. This error is returned when the request hits an undefined route, or if the resource doesn't exist (e.g. has been deleted).

  • 406 error: blocked

  • 413 Request Entity Too Large - The request exceeded the maximum allowed payload size. You shouldn't encounter this under normal use.

  • 422 Invalid Request - The request data is invalid. This includes most of the base-specific validations. You will receive a detailed error message and code pointing to the exact issue.

    • 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".

    • 422 error: FAILED_STATE_CHECK

      • Error meaning - values and/or parameters in the endpoint path have been mismatched

      • Troubleshooting steps - Review the URL path and parameters to verify that the values indicated match and/or exist. This includes base Ids (aka application Ids), Table Ids, View ids, record Ids, etc.

      • Example: Let’s say you have a base that includes Table A and Table B. Further, Table A includes View 1 whereas Table B includes View 2. If you make a request to the List records endpoint with Table A but use View 2 as a parameter, the request will error because View 2 does not belong to Table A.

    • The 422 error may also occur when adding single-select or multiple-select field values using "typecast" without creator permissions on a base.

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

Server error codes

These errors generally represent an error on our side. In the event of a 5xx error code, detailed information about the error will be automatically recorded, and Airtable's developers will be notified. 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.

  • 500 Internal Server Error - The server encountered an unexpected condition.

  • 502 Bad Gateway - Airtable's servers are restarting or an unexpected outage is in progress. You should generally not receive this error, and requests are safe to retry.

  • 503 Service Unavailable - The server could not process your request in time. The server could be temporarily unavailable, or it could have timed out processing your request. You should retry the request with backoffs.

Example error responses

403 - You don't have the right permission for the resource, or the resource was not found

Check that both you and the token have access to the resource. For example, to access a base using a personal access token, your user must be a collaborator and the token must also have access to the base. See this guide for more details.

403 Forbidden
{
  "error": {
    "type": "INVALID_PERMISSIONS_OR_MODEL_NOT_FOUND",
    "message": "Invalid permissions, or the requested model was not found. Check that both your user and your token have the required permissions, and that the model names and/or ids are correct."
  }
}

You don't have permission to create records in the given table. This is returned both when creating records directly, and when creating linked records while updating cell values. Check whether the table or any fields you are setting values for have editing permissions limited.

403 Forbidden
{
  "error": {
    "type": "INVALID_PERMISSIONS",
    "message": "You are not permitted to create records in table TABLE_NAME (TABLE_ID)"
  }
}
403 Forbidden
{
  "error": {
    "type": "INVALID_PERMISSIONS",
    "message": "You are not permitted to write cell values in field FIELD_NAME (FIELD_ID)"
  }
}

You don't have the right permission for the action.

403 Forbidden
{
  "error": {
    "type": "INVALID_PERMISSIONS",
    "message": "You are not permitted to perform this operation"
  }
}

404 - The path is not valid

404 Not Found
{
  "error": "NOT_FOUND"
}
404 Not Found
{
  "error": {
    "type": "NOT_FOUND"
  }
}

422 - The path is correct, however, the body is either not understood or not permitted

422 Unprocessable Entity
{
  "error": {
    "type": "INVALID_REQUEST_UNKNOWN",
    "message": "Invalid request: parameter validation failed. Check your request data."
  }
}

503 - The server is temporarily unavailable and the request should be retried

The Retry-After header may be provided.

503 Service Unavailable
{
  "error": {
    "type": "RETRIABLE_ERROR",
    "message": "Server encountered an error while processing your request, and it is safe to retry the request"
  }
}

Troubleshooting API issues

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

  • 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. For more information, please consult this article.

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

Support interaction guidance

If the troubleshooting steps outlined above have not helped to resolve your issue, then feel free to reach out to our support team. Please include the following information when you submit your help request:

  • The full API request (Please omit your secret access token)

  • Any error messages you are receiving

  • Relevant and specific context around the particular issue you are encountering


Was this article helpful?