Errors and Rate Limits
When a NocoDB API request fails, the response has an HTTP status code and, in most cases, a JSON error body. Match on the error code, not on the message.
Error response
Most errors return an error code and a message, plus details when there is extra context:
{
"error": "ERR_FEATURE_NOT_SUPPORTED",
"message": "Accessing api token api require enterprise plan"
}| Field | Description |
|---|---|
error | A stable code that a program can match, for example ERR_TABLE_NOT_FOUND. It is not present on an unhandled server error. |
message | A description of the problem for people. The text can change between releases. |
details | More context, for example the failed validation entries of a request body, or the plan, limit and current count when a plan limit refuses the request. It is not present when there is no more context. |
Some older endpoints return only {"msg": "<text>"}, with no error code.
Status codes
| Status | Meaning |
|---|---|
400 | The request body or a query parameter failed validation. |
401 | No credential was sent, the credential is not valid, or the operation does not accept this kind of credential. |
403 | The request is authenticated but not allowed: the role is too low, the token scope does not cover the operation, or the plan does not include the feature or allows no more of this resource. |
404 | The resource does not exist. Hooks and documents return 404. Most other resources return 422. |
422 | The request is well formed, but NocoDB cannot act on it. Usually a base, table, field, view, script, dashboard, widget or workflow that the request names does not exist. |
429 | The rate limit is exceeded. See Rate Limits. |
500 | An unexpected server error. The body has a message and no error code. |
Rate Limits
NocoDB APIs have rate limits. The limits keep usage fair and performance good for all users. The default rate limit is 5 requests per second per user. These limits are the same on all plans.
If you go above these limits, the API returns a 429 status code (Too Many Requests). Wait 30 seconds before you send more requests.
To keep good service performance, NocoDB can change these limits or add more rate tiers for pricing plans.
All API tokens of one user share the same limit. A 429 response has these headers:
| Header | Description |
|---|---|
Retry-After | How long to wait before you try again. |
X-RateLimit-Limit | The number of requests allowed in the current window. Sent only on API token requests. |
X-RateLimit-Remaining | The number of requests left in the current window. Sent only on API token requests. |
X-RateLimit-Reset | The time until the current window resets. Sent only on API token requests. |
The body of a 429 response is a JSON string, for example "ThrottlerException: Too Many Requests", not the error object above.
Request IDs
Outside the Community Edition, every NocoDB API error response carries an x-request-id header. In the v3 APIs, the error body also has a requestId field with the same value. Send this id with a bug report. It names the exact call that failed.
To use an id of your own, set an x-request-id header on the request. NocoDB keeps your value when it is 100 characters or less and has only letters, digits, _, ., :, and -. For any other value, NocoDB uses an id of its own.
Related
Last updated on