Airtable API: Common troubleshooting

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

  • 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, follow the guidance listed here.

• 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 follow the guidance listed here.

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

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)"
  }
}

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

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

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

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

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

Support interaction guidance

If the troubleshooting steps outlined above have not helped to resolve your issue, then:

• 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

• Contact Airtable Support by clickingon the lower right corner.