# Fix common API errors

> What each REST API error status and message means, why it happens and how to fix it, plus the mistakes that make filters and connections fail.

Source: https://tadabase.com/docs/developers/error-handling  
Status: Verified Nov 17, 2026. Checked against the current product

When the REST API cannot do what you asked, it answers with a JSON body that has `"type": "error"` and a message in `msg`. Find the message below to see why it happened and how to fix it.

## What an error looks like

```json
{
  "type": "error",
  "msg": "The method being used is disabled for this API key."
}
```

> **Check type, not only the status code:** A few errors come back with HTTP status `200`. Reading records from a table ID that does not exist returns `200` with `"msg": "Data Table not found"`, and reading one record that does not exist returns `200` with `"msg": "Record Was Not Found."`. Treat any response with `"type": "error"` as a failure.

## Credential and account errors (401, 403)

Every request needs the three headers `X-Tadabase-App-id`, `X-Tadabase-App-Key` and `X-Tadabase-App-Secret`. Copy the values from **Settings** > **API Keys**: click the key to see **App ID**, **API Key** and **API Secret**. See [Get your API keys](https://tadabase.com/docs/developers/getting-api-keys).

| Status and message | Cause | Fix |
| --- | --- | --- |
| `401` The credentials supplied are missing or invalid. | One of the three headers is missing or empty. | Send all three headers on every request. Check your HTTP client or proxy does not drop them. |
| `403` The API was not found. | The app ID, key and secret do not match a key of that app: a typo, a key from another app, or a key that was deleted. | Copy all three values again from the key in **Settings** > **API Keys**. |
| `403` The API is currently disabled. | The key is switched to **Inactive**. | Open the key and switch it back to **Active**, or use another key. |
| `403` This API key has expired. | The key's **Expires on** date has passed. | Change or clear **Expires on**, or create a new key. |
| `403` This API key cannot be used from this IP address. | The key has **Allowed IP addresses** and the request came from an address not on the list. | Add the server's IP address or CIDR range to **Allowed IP addresses**, or call from an allowed address. |
| `403` The app was not found. / The app is inactive. | The app was deleted or is not active. | Check the app in your apps list. |
| `403` The account is inactive. / This account's subscription is past due. / This account's subscription is unpaid. / This account's subscription has been canceled. / The account subscription has expired | The account that owns the app has a billing or account problem. The API stops answering until it is resolved. | Sign in as the account owner and check **Billing**. |

## Permission and plan errors (412, 403)

| Status and message | Cause | Fix |
| --- | --- | --- |
| `412` The method being used is disabled for this API key. | The key does not have the permission this endpoint needs, for example **Allow Reads** for reading records, **Allow Updates** for creating and editing, **Allow Delete**, **Allow Logs**, **Allow Webhooks** or **Allow Formula Runs**. | Open the key in **Settings** > **API Keys**, switch on the permission and save. `GET /api/v1/status` lists what the key may do. |
| `412` with a message about your plan | Your plan does not include REST API access, or does not include this part of the API (such as logs, tasks, imports or exports through the API). | Compare plans on the [pricing page](https://tadabase.com/pricing). |
| `403` Row-level security doesn't let this user create this record. (or update, or delete) | The request carries an app user's token (`Authorization: Bearer` or `X-TB-TOKEN`), and that user's row-level security rules do not allow the change. | Make the change as a user who is allowed, change the rules, or send the request without a user token so it runs with the key alone. |
| `403` Row-level security doesn't let this user change these fields: ... | Same as above, for the fields named in the message. | Leave those fields out of the request, or change the rules. |

Read more about rules in [Row-level security](https://tadabase.com/docs/get-started/row-level-security).

## Not found (404)

| Status and message | Cause | Fix |
| --- | --- | --- |
| `404` Invalid API Path | The URL does not match any endpoint. This body has only `msg`, no `type`. | Check the path for typos and that it starts with `/api/v1/`. Compare it with the same call in the **API Playground**. |
| `404` Record Was Not Found. | A delete request named a record that does not exist, or was already deleted. | Check the record ID. Use the encoded `id` the API returns, not a display value. |
| `200` Data Table not found | A read named a table ID that does not exist in this app. (A save to a missing table returns `400` with the same message.) | List the tables with `GET /api/v1/data-tables` and use the `id` from there. |

## Request problems (400, 409, 422)

| Status and message | Cause | Fix |
| --- | --- | --- |
| `400` No Fields Supplied to be Saved. | A create or update request had no values that could be saved. | Send the values as form fields or JSON, keyed by field slug (such as `field_33`). |
| `400` (field name) must be unique. Please enter a unique value. | The field is set to unique and another record already has this value. | Use a different value, or update the existing record instead. |
| `400` Invalid Email supplied in: (field name) | The value sent to an Email field is not a valid email address. | Send a valid address, or leave the field out. |
| `400` Filter field ... isn't a field of this table. | A filter names a field that is not on this table. | Use a field slug of this table. `GET /api/v1/data-tables/{tableId}/fields` lists them. |
| `400` Filter field ... doesn't exist. If it was deleted, restore it from Deleted Fields or change the filter. | The filter names a field that was deleted. | Restore the field, or remove it from the filter. |
| `400` None of the requested fields exist on this table: ... | Every name in the `fields` parameter is unknown. | Use field slugs of this table in `fields`. Unknown names next to valid ones are ignored. |
| `409` | Saving the record was refused because of a duplicate value. | Check unique fields, or update the existing record. |
| `422` with a message naming the parameter | The workflow, import and export endpoints answer `422` when a parameter has a value they do not accept, for example `The runMode parameter must be live or dry. Omit it to start a live run.` | Change the parameter as the message says. |

## Too many requests (429)

| Message | Cause | Fix |
| --- | --- | --- |
| There has been too many attempts in the last minute. Please try again soon. | Your account used its requests for this minute. | Wait the seconds in `X-Retry-After`, then retry. |
| There has been too many attempts in the last 24 hours. | Your account used its requests for the day. | Wait for `X-Daily-Retry-After`, and reduce how many requests you send. |
| Too many failed requests. Please check your API credentials and try again later. | Many requests from your IP address had missing or wrong credentials, so it is blocked for a short time. | Fix the credentials first, then wait a few minutes before trying again. |

See [API rate limits](https://tadabase.com/docs/developers/rate-limiting) for how the limits are counted and a retry example.

## Server errors (500)

A `500` means something failed on our side while handling the request. Retry after a short wait, waiting longer after each failure. If the same request keeps failing, contact Tadabase support with the time of the request, the method and URL, and the response body.

## Common integration problems

### A filter returns every record

A condition the API cannot use is skipped, and a skipped condition matches every record. Check each filter item:

- The item uses the keys `field_id`, `operator` and `val`. Other names, such as `condition` or `value`, are not read.
- `field_id` is a field slug of the table you are reading, such as `field_33`. `GET /api/v1/data-tables/{tableId}/fields` lists them.
- `operator` is one of the operators the field type supports, written exactly as listed in [Filtering records](https://tadabase.com/docs/developers/filtering-records).
- Compare `total_items` in the response with the number of records you expect.

### A connection field stays empty

- Send the record IDs of the connected records, the encoded `id` values the API returns, not their names or other display values. A value that is not a record ID is ignored.
- Send several IDs as an array (`["id1", "id2"]`) or as one comma-separated string.
- Make sure the connected records exist in the table the field connects to.

### A record is not created or changed

- Read `type` and `msg` in the response. A save that worked returns `"type": "success"`, `"msg": "The record has been successfully saved."` and the `recordId`.
- Check the key has **Allow Updates**. Without it, the save returns `412`.
- Check the field slugs in the body. Values under names that are not field slugs of the table are not saved.
- If the request sends an app user's token, that user's row-level security rules apply to the save.

## Try the request and find it in the logs

- **Try it in the API Playground.** Open **Settings** > **API Keys** and click **API Playground** to send the same request from the builder and see the exact response.
- **Look up your usage.** **View Daily Usages** on the same screen shows how many requests each key made per day. See [See every API request in the logs](https://tadabase.com/docs/developers/api-request-logs).
