# 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](#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](#daily-and-monthly-volume-limits) | Start a verification | `volume_limit_reached` |
| [Destination cooldown](#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](manage-applications.html#otp-verification-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](callbacks.html#otp-verification-callbacks) 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](../account-settings/notifications.html#user-panel-notifications-descriptions) 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](api-reference/start-verification.html#otp-verification-api-start-cooldown).

## 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.