Skip to content

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.

Spend cap (plan)Monthly spending cap (yours)
What it isA plan setting: overage on database storage, data transfer and backup storage is not chargedA dollar amount you set for the organization
DefaultOn for Solo, off for Team; Free has hard limits instead; Enterprise follows its contractNo cap
What it blocksPlatform-service allowances become hard limits instead of being billedNew databases and resizes that would take this month’s spend over the amount
WhereShown on BillingBilling → 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: “size s2 exceeds 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 BAA
  • team_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:

shell
zb api GET /v1/orgs/{org}/quotas

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.

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.

Billing has frozen new resources (an open charge dispute, or a freeze by our billing team). See Invoices and payment.

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.

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.