Errors
The Airtable Web API follows HTTP status code semantics.
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 condition and human-readable message 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.
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.
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).
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.
429 Too Many Requests
The API is limited to 5 requests per second per base. You will receive a 429 status code and a message "Rate limit exceeded. Please try again later" and will need to wait 30 seconds before subsequent requests will succeed. To learn more about rate limits, please visit our Rate Limits guide.
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.
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
404
The path is not valid.
404 Not Found{"error": "NOT_FOUND"}
404 Not Found{"error": {"type": "NOT_FOUND"}}
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)"}}
You don't have permission to update cell values in the given field. Check whether the field has editing permissions limited.
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"}}
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."}}
429
The request has been rate limited.
429 Too Many Requests{"error": {"type": "RATE_LIMIT_REACHED","message": "Rate limit exceeded. Please try again later"}}
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"}}