What Should an API Return When a Customer Reaches a Quota?

Api quota exceeded behavior: what to decide

A generic server error encourages a client to retry repeatedly. If the real problem is a monthly quota, retries only waste resources and obscure the customer’s next step. Commercial limits deserve their own error semantics.

Define a stable error code, affected meter, reset or recovery information and a human-readable explanation. Avoid leaking other customers’ quantities. Technical rate limits and purchased quotas should remain distinguishable even if both prevent a request.

An example with the numbers exposed

A client receives monthly_quota_exceeded with the account’s reset date. It can pause a batch instead of retrying every second. A request-per-second limit may instead need a short retry delay; these are different recovery paths.

The mistake worth avoiding

Do not choose an HTTP status in isolation and assume that explains everything. Client libraries often need a consistent structured body, and long-running jobs may reach the limit after initial acceptance.

A practical checklist

• Document quota and rate-limit error contracts.
• Explain whether rejected work is billed.
• Test SDK handling and user-visible messages.
• Provide recovery information without exposing sensitive account data.