Limits and Quotas
Overview and use cases
The platform imposes two kinds of limits on projects/accounts:
Quota Limit (quota): a stock limit with four fields—
databaseStorageLimit(database storage, bytes),storageLimit(object storage, bytes),databasesPerProject(number of project databases),tablesPerProject(number of tables). Defaults: 200MB =209715200bytes ×2,5,100.0means unlimited (effective only when the inherited parent ceiling also allows it); an omitted field means unchanged.RateLimit (rate limiting): a cap on the number of requests per unit of time, sharing with Quota the three-tier ceiling model global → account ceiling → project override. Fields must bepositive integers (there is no “0=unlimited” semantics). Project-level fields and defaults (period defaults to 60 seconds):
accountDefault=300000,projectDefault=30000,apiKeyDefault=600,projectUserDefault=60,consoleDefault=60,anonymousDefault=60; there is also a global guardprojectCreateRate=300(project-creation rate control, not a project-level override).
Prerequisites
Project-level Quota reads/writes use the Console context (
X-Appwrite-Project: console) and a valid Console Session/JWT; theprojectIdin the URL is the target business project. The corresponding scopes areprojects.read/projects.write(RESTGET/PATCH /projects/:projectId/quota-limits). Account-level goes throughAccount.getQuotaLimits/updateQuotaLimits/deleteQuotaLimits(REST/account/quota-limits); credentials must be bound to the current user, and the Console Session/JWT path on this page is recommended. For account Key automation, follow “Account-level quota” below by loading both the account Key and the owning user ID; you cannot reuse the business project Key.Project-level
/limitsadditionally requires a platform admin, the account owner, or the owner of the team the project belongs to; an ordinary business project API Key cannot substitute for a Console identity. A single rate-limit + quota read/write uses RESTGET/PATCH /projects/:projectId/limits; account-level uses/account/limits(PATCH body is{ overrides: { …10 个字段 } }).Internal management plane (account ceilings / project overrides):
GET/PUT /_internal/admin/limits/accounts/:accountId,GET/PUT /_internal/admin/limits/projects/:projectId—for instance-management automation only, not an application integration surface.
The APPBASE_ENDPOINT in the examples includes /v1; APPBASE_SESSION_COOKIE is the full Cookie (name and value) obtained after login, loaded from a controlled local environment. The Cookie may also be replaced with a X-Appwrite-JWT short-term user JWT; do not mix in the business project Key at the same time.
Usage workflow
Read the current quota: use the Console SDK (Node.js / Java) or REST to read
GET /projects/:projectId/quota-limits, which returnsquota/sources/accountLimit/globalLimit—sourcesexplains whether each field value comes from the project override, the account ceiling, or the global default.Update the project quota: use the Console SDK (Node.js / Java) or REST to call
PATCH /projects/:projectId/quota-limits—a partial update; omitted fields are unchanged;0means unlimited (requires the parent ceiling to allow it).Account-level quota:
account.getQuotaLimits()/updateQuotaLimits(...)/deleteQuotaLimits(...)(deleting the override falls back to the inherited value);listLimitsProjects()is exposed only in some SDKs—see SDK differences for details.Rate-limit tuning:
PATCH /projects/:projectId/limits, with a body of 5 flat rate-limit fields + 4 quota fields; the response containsrateLimit/quota/accountLimit/overrides. When the Console SDK has no typed wrapper for this API, useclient.call('patch', ...), or use REST.
Key parameters and returns
Field name pitfalls: when setting, use
databaseStorageLimit; project responses only contain the legacy compatibility fieldauthDatabasesStorageLimit;GET /v1/projects/:projectIddoes not returnstorageLimit— always treat the quota/limits response as the source of truth for valid values, and do not readproject.storageLimit.Quota
0= unlimited; RateLimit has no such semantics (must be a positive integer).Quantity limit violations throw an error at creation time:
database_limit_exceeded,table_limit_exceeded.
Errors and boundaries
database_storage_limit_exceeded/storage_limit_exceeded: HTTP 413 — read quotas before writing/uploading or budget on the business side.Rate limit triggered: HTTP 429 — back off according to the retry guidance in the response; do not stack multiple Keys to bypass it (the ceiling converges at the account level).
Updating a quota is an overwrite semantic: GET first to confirm
sources, avoiding accidentally writing an inherited value as a project override.
SDK Category Differences
Server SDK (server-sdk/nodejs.md): Node.js
Projectshas no project-level quota or/limitsmethods;Accountsupports account-level quota andlistLimitsProjects().Console SDK (console-sdk/nodejs.md): Node.js
Projects.getQuotaLimits/updateQuotaLimitscan read and write project quota;Accounthas account-level quota read/write but nolistLimitsProjects(); useclient.callwhen the/limitsinterface has no typed wrapper.Client SDK (client-sdk/web.md):
Accountsupports current account-level quota andlistLimitsProjects(); it does not provide project-level quota or/limitsmanagement.The Java Console SDK's
Projectsalso provides project quota methods; use REST when Java Server, Python, Go, and the Web SDK lack project-level typed methods.
Examples by language
The following gives examples by language item by item according to the usage workflow; each card can switch invocation methods; project quota and rate-limit cards share a selection, while the account quota card has its own credential path selection.
Project Quota Read/Write
Project-level Quota four-field read/write: reads return quota / sources / accountLimit / globalLimit, writes are partial updates (omitted fields unchanged). The Node.js Console SDK and Java Console SDK provide project quota methods; the Server SDK, Python / Go Console SDK, and Web SDK have no project-level typed methods, so use REST.
- Node.js (Server)
- Console (Node.js)
- REST (curl)
// Projects in agentbase-node-sdk@2.12.0 has no project-level getQuotaLimits / updateQuotaLimits.
// For project quota, use the Console SDK tab or REST below; the Server SDK's Account only manages account-level quota.import { Client, Projects } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // Must include /v1
.setProject('console')
.setCookie(process.env.APPBASE_SESSION_COOKIE!); // Console Session; do not use a project API Key
const projects = new Projects(client);
const quota = await projects.getQuotaLimits({ projectId: '<projectId>' });
await projects.updateQuotaLimits({ projectId: '<projectId>', tablesPerProject: 120 });# Read project quotas: returns quota / sources / accountLimit / globalLimit
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE"
# Partial update (fields not passed remain unchanged; 0 = unlimited)
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"tablesPerProject":120}'
# Account level: GET/PATCH /account/quota-limits (use DELETE to remove an override and fall back to the inherited value)Account-Level Quota (Account Quota)
Account-level read/write of /account/quota-limits determines the account from the user identity in the request; permissions cannot be inferred from the SDK type alone. The Web Client can use the current user's Session; when managing platform accounts, use the Console context and that account's Session/JWT.
Server-side automation uses this path only when the target environment has issued and confirmed valid an Account API Key for the platform account; the Key must have the account scope, and you must also provide X-Appwrite-Project: console, X-Appwrite-Key, and the X-Appwrite-User of the user who owns the Key. The scope set of ordinary project Keys does not include account; you cannot substitute a project ID for a user ID, nor call only setKey while omitting the user header. Account Keys and Session/JWT are used separately and are not mixed in the same Client; credentials are loaded only from controlled environments and are never written to documentation, repositories, or logs. This page does not assume the target deployment has account Key issuance available; when there is no confirmed valid account Key, use the Console Session/JWT.
updateQuotaLimits partially updates the four fields; deleteQuotaLimits deletes the override and falls back to the inherited value. Client Web, Server Node, and Server/Console Java also provide listLimitsProjects; Console Node has quota read/write but not that list method, and Server Python/Go also provide their own language's account-level quota APIs. The existence of generation methods does not mean ordinary project Keys can call them, and the account-level capabilities above are not equivalent to project-level quota support.
For Client SDK read examples, see client-sdk/web.md and JavaScript examples; this page's Console and REST tabs show the account management path.
- Console (Node.js)
- Node.js(账号 Key)
- REST (curl)
// Account level uses Console Session/JWT (not a project API Key)
await sdk.forConsole.account.getQuotaLimits();
await sdk.forConsole.account.updateQuotaLimits({ tablesPerProject: 120 }); // Partial update of the four quota fields
await sdk.forConsole.account.deleteQuotaLimits(); // Delete the override and fall back to the inherited value
// The Console Node SDK does not provide listLimitsProjects()import { Account, Client } from 'agentbase-node-sdk';
// Create a separate Client; the account key must have the account scope, and the user ID must be the owner of that key.
const accountClient = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // Includes /v1
.setProject('console')
.setKey(process.env.APPBASE_ACCOUNT_API_KEY!)
.addHeader('X-Appwrite-User', process.env.APPBASE_ACCOUNT_USER_ID!);
const account = new Account(accountClient);
const quota = await account.getQuotaLimits();curl -sS "$APPBASE_ENDPOINT/account/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE"
# Partial update (fields not passed remain unchanged): PATCH /account/quota-limits
curl -sS -X PATCH "$APPBASE_ENDPOINT/account/quota-limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"tablesPerProject":120}'
# DELETE /account/quota-limits: deletes the override and falls back to the inherited valueRate Limit Tuning (Comprehensive /limits: rate limits + quotas)
/limits reads and writes 5 rate-limit fields + 4 quota fields in one call; rate-limit fields must be a positive integer (there is no 0=不限 semantic), and the response contains rateLimit / quota / accountLimit / overrides. The Web Client only provides account-level quota, not project-level quota or rate-limit management; typed methods for project-level /limits exist only in console-java Projects (getLimits(projectId) / updateLimits(projectId, 5 个限频字段 + 4 个配额字段) / deleteLimits(projectId, keys)); server-java / server-python / server-go all lack Projects, so use REST uniformly (use client.call when the Console has no typed wrapper, see inside the card); account-level /account/limits has typed methods in Server/Console SDK versions Account that provide the feature.
- Node.js (Server)
- Console (Node.js)
- REST (curl)
// Projects in agentbase-node-sdk@2.12.0 has no getLimits / updateLimits.
// For project rate limits, use the Console tab or REST below; the Account method of the same name is an account-level interface.// Console SDK has no typed getLimits/updateLimits: call REST directly via client.call
client.setProject('console');
const limitsUri = new URL(`${client.config.endpoint}/projects/${projectId}/limits`);
const limits = await client.call('get', limitsUri, {}, {});
await client.call('patch', limitsUri, { 'content-type': 'application/json' }, {
projectDefault: 30000, apiKeyDefault: 600, projectUserDefault: 60,
consoleDefault: 60, anonymousDefault: 60,
databaseStorageLimit: 209715200, storageLimit: 209715200,
databasesPerProject: 5, tablesPerProject: 100
});# Combined read/write: the PATCH body is a flat set of 5 rate-limit fields + 4 quota fields
curl -sS "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE"
curl -sS -X PATCH "$APPBASE_ENDPOINT/projects/<projectId>/limits" \
-H "X-Appwrite-Project: console" \
-b "$APPBASE_SESSION_COOKIE" \
-H 'Content-Type: application/json' \
-d '{"projectDefault":30000,"apiKeyDefault":1200,"projectUserDefault":60,"consoleDefault":60,"anonymousDefault":60,"databaseStorageLimit":209715200,"storageLimit":209715200,"databasesPerProject":5,"tablesPerProject":100}'
# Account ceiling: PATCH /account/limits, body is {"overrides":{…10 fields}}; not a project-level overrideExample Guide
JavaScript (Web reads/writes account quota, Console Node reads/writes project quota): examples/javascript.md