API limit errors
When an API request can’t be paid for, by the plan or by usage credits, the Syntic API answers with HTTP 402 and the error quota_exhausted. The response tells you which limit was reached and when it resets, so your code can decide whether to wait or alert a person. The same rules apply to Syntic Code, which uses the API.
What the response contains
| Field | Meaning |
|---|---|
error | quota_exhausted |
limit | Which limit: monthly, weekly, session, spend_limit or no_credits |
message | A readable explanation (below) |
resets_at | When the limit reopens, as a date and time in UTC |
upgrade_url | Where to upgrade the plan |
add_credit_url | Where to add credit |
The response also carries an x-syntic-request-id header. Include it if you contact support.
The messages
limit | Message (the reset sentence appears when a reset time is known) |
|---|---|
monthly | Your monthly plan token allowance is used up. It resets at (time). Upgrade your plan or enable usage credits to keep going. |
session | You’ve hit your 5-hour session usage limit. It resets at (time). Enable usage credits or upgrade your plan to keep going. |
weekly | You’ve hit your weekly usage limit. It resets at (time). Enable usage credits or upgrade your plan to keep going. |
spend_limit (organization) | Your monthly usage-credit spend limit has been reached. It resets at (time). Raise the spend limit in billing settings to keep going. |
spend_limit (member) | Your monthly member spend limit has been reached. It resets at (time). Ask an org admin to raise it. |
no_credits | Your plan limit is reached and your usage-credit balance is empty. It resets at (time). Buy usage credits to keep going. |
Not a limit: retry
If Syntic can’t check usage at that moment, the API answers 503 with code usage_check_unavailable, the message Usage can’t be verified right now. Please retry in a moment., and a Retry-After header of 5 seconds. Retry after the delay.
Other refusals you may see
- 403
plan_required: the organization is on the Free plan, or its paid plan is inactive. The Free plan covers web chat only; upgrade to use the API.
Code examples for handling these responses are in the developer docs: Handle usage limits and Usage & cost.