Help
Spending caps, quotas and 402, 422 and 429 errors
Tested with:Databasezy API v1 · zb CLI 0.1
When a request would go past your plan’s quotas or your organization’s spending cap, the API refuses it with an error that names the limit. Running databases are never stopped because you reached a cap. The fix is to free up room, raise your cap, or move to a plan with higher limits.
Every API error is a JSON problem (application/problem+json) with a type ending in the kind of problem, a
detail sentence and, for validation errors, an errors list naming the field. The portal and the zb CLI show the
same text.
Two different caps
Section titled “Two different caps”| Spend cap (plan) | Monthly spending cap (yours) | |
|---|---|---|
| What it is | A plan setting: overage on database storage, data transfer and backup storage is not charged | A dollar amount you set for the organization |
| Default | On for Solo, off for Team; Free has hard limits instead; Enterprise follows its contract | No cap |
| What it blocks | Platform-service allowances become hard limits instead of being billed | New databases and resizes that would take this month’s spend over the amount |
| Where | Shown on Billing | Billing → Spending cap and alerts |
The plan fee, compute and add-ons are always billed, whatever the caps say. Turning the plan spend cap on or off is not available in the portal yet; ask in a billing ticket.
422 spending_cap: “the organization’s spending cap of $… /month would be exceeded”
Section titled “422 spending_cap: “the organization’s spending cap of $… /month would be exceeded””Your monthly spending cap is reached. The message shows the cap, the month-to-date spend and the estimate for the request. Creating an instance, or increasing an instance’s size or storage, is refused. Nothing that is already running stops.
To fix it, someone with billing:manage (owners, admins and billing members) raises or removes the cap under
Billing → Spending cap and alerts. Leave the field empty for no cap. Or reduce spend first: pause or delete
instances you do not need.
The same form stores a warning percentage. When month-to-date spend passes it, owners, admins and billing members get an email; add more thresholds, team alerts and webhooks under Spend alerts. You also get notifications when usage reaches 80%, 90% and 100% of an included allowance; they are emailed and listed under Alerts.
422 validation: “instance quota reached (1 of 1)”
Section titled “422 validation: “instance quota reached (1 of 1)””Plan quotas are checked when you create or resize an instance. The error names the field and the limit, for example:
instances: “instance quota reached (1 of 1); upgrade the plan or delete an instance”size: “sizes2exceeds the Free plan maximum (f0)”storage_gb: “the Solo plan allows at most … GB per instance”, or “org storage quota exceeded”replicas,ha,placement: a feature your plan does not include, such as secure placement without a signed BAAteam_quota: your team’s own limit, set by an organization admin
Delete what you no longer need or change plan (Changing plans). On Team and Enterprise you can also ask for a higher limit in a billing ticket. Quotas are listed in Limits and quotas and Platform pricing and limits. Your organization’s current limits and use:
zb api GET /v1/orgs/{org}/quotas402 plan_limit
Section titled “402 plan_limit”The feature or allowance is not in your plan, or this period’s allowance is used up. Examples: SSO and SCIM on Free or Solo, project-scoped roles, more log drains or pipelines than the plan allows, “the plan’s build minutes are used up for this month”, or the daily allowance of database assistant requests. Upgrade, wait for the allowance to reset, or remove something to make room.
402 seat_limit: “seat limit reached”
Section titled “402 seat_limit: “seat limit reached””Free and Solo include one member. Invites count as seats while they are pending. Upgrade to Team for unlimited members, or remove a member or a pending invite. Auditors do not use a seat.
402 billing_frozen
Section titled “402 billing_frozen”Billing has frozen new resources (an open charge dispute, or a freeze by our billing team). See Invoices and payment.
403 quota-exceeded
Section titled “403 quota-exceeded”Returned by object storage when an upload would exceed your storage allowance or a bucket limit. Delete objects or
upgrade. A 403 with type forbidden is a permission problem instead: see
Teams, roles and permissions.
429 rate-limited: “rate limit exceeded; retry in N s”
Section titled “429 rate-limited: “rate limit exceeded; retry in N s””You sent requests faster than the limit. The response carries a Retry-After header (seconds) and RateLimit-*
headers. The REST API allows 600 requests per minute per API key or user (burst 100), 60 per minute per IP without
authentication, and 5 per minute on routes that issue credentials. Project keys at the project endpoint have a
per-plan requests-per-second limit (Project keys).
Wait for Retry-After, then retry with exponential backoff and jitter. Do not retry in a tight loop.
Still stuck?
Section titled “Still stuck?”Search the help center or ask the assistant in the portal Help panel; it can read your plan, quotas and this
period’s usage. If that does not solve it, open a support ticket from the portal (Help → Open a ticket) and
include the full error (type, detail and any errors), the x-request-id response header, the instance id and
region, and the time in UTC. Never paste passwords, connection strings with passwords, API keys or patient data
(PHI) into a ticket. See How to get help.