Quota and plans

Complete developer guide and best practices to help you get started quickly.

Core concept

Explains the difference between quota and request-rate limits, how to read usage from responses, how to monitor proactively, and which error codes you get at the cap.

There are two independent limits. Quota is the cumulative usage for the current period: once it is exhausted you must purchase additional quota or wait for the next contract period — retrying will not help. Request rate is measured in requests per minute (RPM): exceeding it only requires slowing down or retrying later. Both limits are reported at the account level and the API-key level. All API keys currently share the account-level caps for the duration of the contract period, so your effective ceiling is determined by your account plan.

The two quota dimensions

The two dimensions are tracked separately. All API keys currently share the account-level quota and RPM caps for the contract period, and assigning a lower cap to an individual key is not yet available, so both share the same denominator. Their numerators are independent, however: the account level accumulates usage from every key, while the key level counts only that key's own usage. Once your account has more than one key, key_percent is lower than user_percent.

Dimension	Response field	How it is calculated	Error code at the cap
Account level	user_percent	Account's period usage ÷ account cap	quota_exceeded_user (429)
API-key level	key_percent	Calling key's period usage ÷ that key's effective cap (the numerator counts only this key's own usage; the denominator currently resolves to the account-level cap)	quota_exceeded_key (429)

All API keys currently share the account-level caps

Quota and RPM are currently configured at the account level only. Every API key applies the same set of caps for the duration of the contract period, and assigning a lower cap to an individual key is not yet available. Note that a shared cap does not make the two percentages equal: usage is still tracked separately, and key_percent counts only that key's own usage — so once your account has more than one key, key_percent is lower than user_percent, and user_percent is the value that actually reaches the cap first. Create multiple keys to separate environments and to be able to revoke one independently, not to allocate quota. Keep handling the key_percent field and the quota_exceeded_key and rate_limited_key error codes in your integration: they are still returned as usual, and your code will not need to change when key-level caps become available.

Successful responses from the text translation and speech recognition endpoints both carry usage.quota_percent.used, the account-level cumulative usage percentage (0–100). In SSE mode the same value arrives inside the meta event's data.usage.

The usage field in a translation response; used is the account-level cumulative percentage (0–100).

json

{
  "translated_text": "Today's meeting is rescheduled to 3 PM.",
  "detected_source_lang": "zh-TW",
  "usage": {
    "quota_percent": {
      "used": 12
    }
  },
  "forced_replacement_count": 0
}

Proactive monitoring: GET /api/v1/usage

This is a read-only endpoint that consumes no quota and does not count against your requests-per-minute budget, so it is safe to call around business requests or poll periodically from your backend. Unlike the business endpoints, it needs no actual workload and reports both the account-level and key-level dimensions.

curl example for querying current-period usage.

bash

curl "https://abemono.abestar.com.tw/api/v1/usage" \
  -H "X-API-Key: $ABESTAR_API_KEY"

Response example; both fields are percentages in the 0–100 range. Here the account has used 35% of its cap for the period, of which 12% came from the key used in this request and the rest from other keys on the account. Key-level caps currently inherit the account-level cap, so key_percent never exceeds user_percent.

json

{
  "user_percent": 35,
  "key_percent": 12
}

Set an alert threshold at 80%

Once the quota is exhausted, requests are rejected outright — there is no grace buffer. Poll GET /api/v1/usage from your backend and raise an internal alert as soon as either dimension reaches 80%, then contact the sales team to adjust the cap before peak hours. Because the account level accumulates usage from every key, user_percent is usually the one that trips the alert first.

Errors at the limit and how to handle them

Error code	HTTP	Meaning	Recommended handling
rate_limited_user	429	Account-level requests-per-minute exceeded.	Retry with exponential backoff and lower your concurrency.
rate_limited_key	429	This key's requests-per-minute exceeded.	Back off, retry, and lower your concurrency. All keys currently share the same RPM budget, so switching keys will not bypass the limit.
quota_exceeded_user	429	The account's current-period quota cannot cover this request.	Retrying will not help. Check usage via GET /api/v1/usage, then contact the sales team to adjust the cap.
quota_exceeded_key	429	This key's current-period quota cannot cover this request.	Retrying will not help. Key-level caps currently equal the account-level cap — check usage via GET /api/v1/usage, then contact the sales team to adjust the account quota.

There are two kinds of 429 — handle them differently

rate_limited_* is a short-term rate limit that clears after a backoff; quota_exceeded_* means the period quota is gone and retrying will keep failing until the cap is adjusted. When you receive a 429, always read the code field in the response body before deciding whether to retry — never branch on the HTTP status alone.

Plans and add-ons

Quota caps depend on your plan and apply to the whole account; all API keys share those caps for the contract period. Actual plan contents, quota tiers, and add-on options are tailored to your use case — talk to the sales team to find the right fit.

Looking for usage-based pricing?

We will tailor a solution to your requirements.