Limits

The Verification API limits request rates and the number of verifications each OTP application can start. If a request exceeds a limit, the API returns 429 Too Many Requests with a Retry-After header and an errors[].code identifying the limit. The rejected request does not create a verification, send an SMS message, place a call, or incur a charge.

Limit	Applies to	errors[].code
Per-second rate limits	Every /api/v1 endpoint	rate_limit_per_ip, rate_limit_failed_auth, rate_limit_per_account, rate_limit_public_per_account
Daily and monthly volume limits	Start a verification	volume_limit_reached
Destination cooldown	Start a verification	destination_in_cooldown

Per-second rate limits

Each limit counts requests within one clock second. Requests that exceed a limit return 429 Too Many Requests with Retry-After: 1.

Code	Scope	Limit
rate_limit_per_ip	public mode requests from the same IPv4 address or IPv6 /64 network, across all accounts	10 requests per second from one IPv4 address, 2 from one IPv6 /64 network.
rate_limit_failed_auth	Failed authentication attempts from the same IPv4 address or IPv6 /48 network, in any authentication mode	After 5 failed attempts from one IPv4 address or IPv6 /48 network, further requests from it are rejected for the rest of that second, even with valid credentials.
rate_limit_per_account	All requests for the account, from any IP address and in any mode, across all its OTP applications	10 requests per second.
rate_limit_public_per_account	public mode requests for the account, from any IP address	5 requests per second. They also count toward rate_limit_per_account.

basic and application mode requests are not subject to rate_limit_per_ip, so a backend that sends all its requests from one address is not limited by it. Contact DIDWW support if your traffic needs higher per-account limits.

The per-second limits are enforced on a best-effort basis. Apply your own request rate controls instead of relying on these limits to regulate your traffic.

Daily and monthly volume limits

An OTP application can have a daily limit, a monthly limit, or both. New applications default to 1,000 verifications per day and 15,000 per month. You can change these values in the application settings. See Set volume limits.

Leaving a daily or monthly limit empty disables that volume limit. Per-second rate limits and the destination cooldown still apply.

Each volume limit counts verification requests approved for delivery, across all delivery methods. Requests that result in denied, or failed because the destination is not supported, do not count.

Days and months are counted in UTC. A daily limit resets at 00:00 UTC, and a monthly limit at 00:00 UTC on the first day of the month.

When a volume limit is reached, requests to start a verification return 429 Too Many Requests with the volume_limit_reached error code. The Retry-After header gives the number of seconds until the limit resets, which can be hours or days. No verification is created, and nothing is sent or charged. The request callback is skipped if the request is rejected before the callback step. Status and report requests are not affected.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 49320

{
  "errors": [
    {
      "code": "volume_limit_reached",
      "detail": "the application reached its daily or monthly verification limit"
    }
  ]
}

DIDWW emails the recipients of the OTP Applications notification when an application uses 80% of a limit and when it reaches the limit.

Destination cooldown

After a verification is approved for delivery, the OTP application must wait 30 seconds before starting another verification for the same phone number, regardless of the delivery method. Requests made during this interval return 429 Too Many Requests with destination_in_cooldown. See Repeated starts.

Handling 429 responses

Read errors[].code to decide what to do. The Retry-After header is always present.

Code	Handling
rate_limit_per_account, rate_limit_public_per_account, rate_limit_per_ip	Wait at least the number of seconds in Retry-After, then retry with a small random delay and a limited number of attempts. The rejected request had no effect, so retrying it does not duplicate a verification. If these errors continue, spread your requests over time or contact support.
rate_limit_failed_auth	Check the credentials used by requests from the same IPv4 address or IPv6 /48 network and stop repeated failed authentication attempts. Wait at least the number of seconds in Retry-After before retrying.
destination_in_cooldown	Do not retry automatically. Let the user request a new code once the Retry-After interval has passed.
volume_limit_reached	Do not retry automatically. Tell the user that verification is temporarily unavailable and alert your team. Wait until the limit resets, or increase the limit in the application settings to allow more verifications before the reset.

For an unknown error code returned with 429, wait at least the number of seconds in Retry-After and avoid automatic retries until you understand the cause.