Rate limits
Every plan comes with a request quota. Read the headers, pick the right plan and back off before you are throttled.
Every API is rate limited. Limits are checked before your request is processed,
so exceeding them costs you nothing but a 429.
Reading the headers
Every response carries your current standing:
curl -i -X POST https://api.kongapj.com/sms/v1/messages \
-H "apikey: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"+61400000000","from":"Optus","message":"Hi"}'
HTTP/1.1 201 Created
RateLimit-Limit: 60
RateLimit-Remaining: 59
RateLimit-Reset: 47
X-Correlation-ID: 8f14e45f-ce...
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests permitted in the window |
RateLimit-Remaining | Requests still available |
RateLimit-Reset | Seconds until quota is restored |
Read RateLimit-Remaining and back off before you hit zero, rather than
waiting to be rejected.
When you exceed the limit
HTTP/1.1 429 Too Many Requests
RateLimit-Remaining: 0
Retry-After: 43
{
"message": "API rate limit exceeded"
}
Wait for Retry-After seconds. Retrying sooner just consumes quota you do not
have and keeps you rejected for longer.
Two stacked controls
Requests pass through two independent limits. Either one can return a 429, and
both must be satisfied for a call to proceed.
Per-minute quota
Your plan's overall allowance — 60, 600 or 6000 requests per minute — counted per registered application over a sliding window.
Burst protection
A short one-second window that smooths sudden bursts, so a spike of traffic cannot spend your whole minute at once.
Burst protection keeps a sudden flood from overwhelming your quota even when you are comfortably under your per-minute allowance: it encourages traffic to arrive as a steady stream rather than in spikes. Spread your calls evenly and you will never trip it.
Plans
Each API offers tiered plans. You pick a plan when you register an application, and the limit applies per application.
| Plan | Rate limit | Suited to |
|---|---|---|
| Free | 60 req/min | Prototypes and evaluation |
| Pro | 600 req/min | Production workloads |
| Enterprise | 6000 req/min | High-volume, business-critical traffic |
Usage is metered against your plan, so you can track consumption in real time. Moving up a tier is a matter of registering against a higher plan — no code change, no new credential.
Tracing a request
Every response includes an X-Correlation-ID. Quote it when reporting a
problem: it uniquely identifies your request to Optus support.