“Limit exceeded” is not enough information for an API client to choose a correct recovery action. A developer needs to know which limit was exceeded and what behavior the service expects next.
Quick answer: Document request rate, concurrency and cumulative allowance separately. Specify each limit’s unit, identity scope and time behavior. Explain the error representation and any retry guidance without promising that a standard status code defines the provider’s commercial policy.
Use separate definitions
For an illustrative extraction API, these constraints could coexist:
| Constraint | Question it answers |
|---|---|
| Request rate | How quickly may this identity submit requests? |
| Concurrency | How many operations may be in progress at once? |
| Period allowance | How much measured usage is included during the period? |
| Payload restriction | How large or complex may an individual request be? |
No specific rates in this article are claimed as API.market or provider limits. Inspect the selected product’s actual documentation.
Tie the error to a policy
A useful error reference identifies the condition, whether the operation was accepted and the relevant next step. When available, preserve a request identifier so support can investigate the event without asking the developer to publish a credentialed request.
RFC 6585 defines 429 Too Many Requests and permits Retry-After guidance. The standard leaves the service’s user-identification and request-counting policy to its implementation. A client should therefore not assume that every 429 shares the same scope or reset behavior.
If the provider supplies Retry-After, document how clients should interpret it. If another field describes allowance reset, explain that separately. Do not invent a header name or imply that every service exposes remaining capacity.
Show examples that lead to different actions
Include a burst restriction, an exhausted period allowance and a concurrency rejection in the documentation when those conditions exist. Make clear whether the developer should wait, reduce parallel work, inspect the plan or take another supported action.
For operations with side effects, a client also needs to understand retry safety. RFC 9110’s idempotency definition is a foundation, but product-specific behavior and documented replay guarantees still matter.
Keep SDK behavior aligned
If an SDK retries automatically, document which errors it handles, its stopping condition and what it exposes when attempts are exhausted. A dashboard that reports attempts should not silently imply those attempts were distinct successful tasks.
I’m Shashank Agarwal, creator of API.market and founder and CEO of Noveum AI. Review actual plan details through the subscription guide, and see the metrics guide for the distinction between activity and business results.
Follow my work on LinkedIn. Drafted with AI assistance.
