OTP.ID API Rate Limits: Global and Per-Destination Policies

OTP.ID enforces two independent rate-limiting policies: a global per-API-key limit that applies to every endpoint, and a per-destination limit that protects individual users from receiving too many OTP messages in a short period. Both limits return HTTP 429 responses with distinct error codes so you can handle them separately. IP allowlisting is separate from rate limiting. If your merchant has an API V3 IP whitelist, requests from an unlisted resolved IP are rejected with HTTP 403 and IP_NOT_ALLOWED; they do not become 429 rate-limit responses. See the API V3 IP allowlist guide.

Summary

Policy	Scope	Limit	Error Code
Global	All `/v3/*` endpoints, per API key	20 requests / second	`RATE_LIMITED`
Per-destination (short window, standard channels)	`POST /v3/request` and `POST /v3/send`, per destination	5 OTPs / 10 minutes	`DESTINATION_RATE_LIMITED`
Per-destination (long window, standard channels)	`POST /v3/request` and `POST /v3/send`, per destination	10 OTPs / hour	`DESTINATION_RATE_LIMITED`
Per-destination (short window, `misscall`)	`POST /v3/request` only, per destination	2 OTPs / 10 minutes	`DESTINATION_RATE_LIMITED`
Per-destination (long window, `misscall`)	`POST /v3/request` only, per destination	4 OTPs / hour	`DESTINATION_RATE_LIMITED`

Global per-API-key limit

Every request you make to any /v3/* endpoint counts toward your global rate limit. The window is a fixed 1-second bucket. If your API key sends more than 20 requests within that second — across POST /v3/request, POST /v3/send, POST /v3/verify, GET /v3/otp/{otp_id}, or any other v3 endpoint — all additional requests within that window are rejected. Error response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Terlalu banyak request, coba lagi sebentar"
  }
}

Handling `RATE_LIMITED`

Implement exponential backoff when you receive this error. A simple strategy:

On the first RATE_LIMITED response, wait ~100 ms and retry.
On each subsequent failure, double the wait time (200 ms, 400 ms, 800 ms…).
Add a small random jitter (±20%) to prevent synchronized retries from multiple instances of your service all hitting the limit at the same moment.
Set a maximum retry count (e.g., 5 attempts) and surface an error to the user if all retries are exhausted.

import time
import random

def send_otp_with_backoff(payload, max_retries=5):
    delay = 0.1  # initial delay in seconds
    for attempt in range(max_retries):
        response = call_otp_api(payload)
        if response["success"]:
            return response
        if response["error"]["code"] == "RATE_LIMITED":
            jitter = delay * random.uniform(0.8, 1.2)
            time.sleep(jitter)
            delay *= 2
        else:
            raise OtpApiError(response["error"])
    raise MaxRetriesExceeded()

If you regularly hit the global limit in production, batch your OTP requests or spread them more evenly over time. Contact OTP.ID support to discuss a higher limit for high-volume use cases.

Per-destination limit

When you call an OTP creation endpoint, OTP.ID also enforces a per-destination limit. This limit applies to the combination of your API key (merchant) and the destination phone number or email address — so separate merchants are counted independently. The limit is channel-specific because Missed Call has a four-digit caller-ID OTP that is more susceptible to guessing. For standard channels (whatsapp, sms, and email), two windows are enforced simultaneously:

Short window: No more than 5 OTPs per 10 minutes to the same destination
Long window: No more than 10 OTPs per hour to the same destination

For misscall, which is available only through POST /v3/request, the stricter policy is:

Short window: No more than 2 OTPs per 10 minutes to the same destination
Long window: No more than 4 OTPs per hour to the same destination

Both conditions must be satisfied for a request to succeed. If either window is exhausted, the request is rejected.

This limit applies only to OTP creation endpoints. For Missed Call, that means POST /v3/request only. Calls to POST /v3/verify and GET /v3/otp/{otp_id} are not subject to the per-destination policy.

Error response:

{
  "success": false,
  "data": null,
  "error": {
    "code": "DESTINATION_RATE_LIMITED",
    "message": "Terlalu banyak OTP ke nomor ini, coba lagi nanti"
  }
}

Why this limit exists

The per-destination limit protects your users from OTP flooding — a situation where an attacker (or a bug in your application) repeatedly triggers OTP messages to the same phone number or email address. Without this limit, a single user could receive dozens of messages in quick succession, which is a poor experience and a potential harassment vector.

Handling `DESTINATION_RATE_LIMITED`

Unlike the global limit, you cannot simply retry immediately — you must wait for the current window to expire before sending another OTP to that destination. Recommended approach:

Track OTP send counts on your side. Maintain a counter per destination in your own cache or database so you can check the limit before calling the API and show users a friendly waiting message instead of an opaque error.
Surface a user-facing message. Tell the user something like “Too many OTP requests. Please wait a few minutes before requesting a new code.”
Do not retry automatically. This error is not a transient failure — retrying the same destination will continue to fail until the window resets.

// Example: client-side guard before calling the API
async function requestOtp(destination, channel = "whatsapp") {
  const recentCount = await getRecentOtpCount(destination, 10 * 60); // last 10 min
  const shortLimit = channel === "misscall" ? 2 : 5;
  if (recentCount >= shortLimit) {
    throw new Error("Please wait before requesting another OTP.");
  }
  const response = await fetch("https://api.otp.id/v3/request", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ channel, destination })
  });
  return response.json();
}

Do not silently swallow DESTINATION_RATE_LIMITED errors and retry in the background — every retry will keep failing until the window resets. Always propagate a meaningful message to the user.

Both limits together

It is possible to receive either limit in a single high-traffic session. The table below summarises how to differentiate them:

Scenario	Error Code	Right response
Your system is making too many API calls per second overall	`RATE_LIMITED`	Exponential backoff, then retry
You’ve sent too many OTPs to one specific number/email	`DESTINATION_RATE_LIMITED`	Wait for the window to expire; notify the user

If you need to increase the global rate limit beyond 20 requests/second, contact OTP.ID support. Per-destination limits are fixed and cannot be adjusted.

Get Started

Core Concepts

Channel Guides

Guides

Reference

OTP.ID API Rate Limits: Global and Per-Destination Policies

Summary

Global per-API-key limit

Handling `RATE_LIMITED`

Per-destination limit

Why this limit exists

Handling `DESTINATION_RATE_LIMITED`

Both limits together

​Summary

​Global per-API-key limit

​Handling RATE_LIMITED

​Per-destination limit

​Why this limit exists

​Handling DESTINATION_RATE_LIMITED

​Both limits together

Summary

Global per-API-key limit

Handling `RATE_LIMITED`

Per-destination limit

Why this limit exists

Handling `DESTINATION_RATE_LIMITED`

Both limits together