# Rate limits and quotas

> Noptcha API rate limits, concurrency, request and image size, waiting and retention limits, and how to handle 429 responses.

Source: https://noptcha.com/docs/limits/

All numbers on this page are **starting values**: they may change, and limits can be raised per organization. `GET /v1/me` returns the values that apply to your key.

## Limits

| Limit | Default | Over the limit: v1 | Over the limit: compatibility API |
| --- | --- | --- | --- |
| Creating tasks | 200 per second per key, bursts of 200 | `429 rate_limited` | `ERROR_NO_SLOT_AVAILABLE` |
| Polling one task | 5 per second, bursts of 10; a long poll (`wait`) counts once | `429 rate_limited` | `processing` (not an error) |
| Tasks in flight | 50 per organization and captcha family | `429 concurrency_limited` | `ERROR_NO_SLOT_AVAILABLE` |
| Invalid keys | 50 per IP address in 10 minutes, then blocked for the rest of the window (IPv6: per /64; 500 per /48) | `429 rate_limited` | `ERROR_IP_BLOCKED` |
| Synchronous wait | at most 90 seconds | — | — |
| Request body | 1 MB for image types, 64 KB for other types | `413 request_too_large` | `ERROR_TOO_BIG_CAPTCHA_FILESIZE` |
| Image size | 8192 pixels per side and 8,388,608 (223) pixels in total per image, read from the file structure (for GIF and WebP the largest of the canvas and every frame) | `422 invalid_params`, pointer to the image (`/params/images/1`), `reason: "image_too_large"` | `ERROR_TOO_BIG_CAPTCHA_FILESIZE` |
| Animated images | at most 1000 frames, and frames × width × height at most 8,388,608 (223) per image; [see below](#images) | same as image size | same as image size |
| All images of one task | frames × width × height of every image added up: at most 33,554,432 (225) | same as image size, pointer to the image that went over | same as image size |
| Results | kept for 10 minutes after the task completes | `404 not_found` | `ERROR_NO_SUCH_CAPCHA_ID` |
| Feedback | for solved tasks, within 10 minutes after completion | `404 not_found` (expired), `409 task_not_solved` | `ERROR_NO_SUCH_CAPCHA_ID` |
| Usage reports | 20 per minute per organization, bursts of 5 | `429 rate_limited` | — |
| Public catalog (`GET /v1/catalog`) | 60 per minute per client IP (IPv6: per /64), bursts of 30; IPv6 also 600 per minute per /48, bursts of 300 | `429 rate_limited` | — |

## Images

Every image is checked when the task is created, before anything is charged:

-   **Encoding**: base64 in the standard (`+/`) or URL-safe (`-_`) alphabet, not both in one image. Missing `=` padding, line breaks, spaces and a `data:image/<type>;base64,` prefix are accepted; the image is passed on to the solver in standard base64 without them. `=` in the middle, any other character or another `data:` prefix is rejected.
-   **Format**: PNG, JPEG, GIF, WebP or BMP only, complete and well-formed (for example, one PNG `IHDR` chunk at the start and an `IEND` at the end; one JPEG frame header and nothing but `0xFF` fill between segments; a GIF that ends with its trailer). Files that common encoders produce pass; files that only a lenient decoder would open do not. Multi-picture JPEG files (MPO, such as some phone camera photos) are not accepted: send a plain JPEG. A JPEG may have at most 100 scans (a progressive JPEG has one per refinement pass; common encoders write 10 or fewer): solvers decode the whole image once per scan.
-   **Size**: the pixel limit above.
-   **Animation** (GIF, APNG, animated WebP): solvers that read every frame hold every frame as a full canvas, so each frame counts as width × height. At most 1000 frames per image, and frames × width × height at most 8,388,608 (for example 1 frame of 2896 × 2896, or 1000 frames of 91 × 91). A typical animated captcha (a few dozen frames of a couple of hundred pixels) is far below this.
-   **Per task**: for types that take several images (`images`, `anchors`), frames × width × height of all images together at most 33,554,432, for example 20 images of 4000 × 400. The first image that goes over the total is reported.

| Problem | v1 `reason` (with `422 invalid_params`) | Compatibility API | 2captcha API |
| --- | --- | --- | --- |
| Over 1,000,000 characters, the pixel or frame limits, or the per-task total | `image_too_large` | `ERROR_TOO_BIG_CAPTCHA_FILESIZE` | `ERROR_TOO_BIG_CAPTCHA_FILESIZE` |
| Not one of the formats above, a multi-picture JPEG, a JPEG with more than 100 scans, malformed or truncated | `image_format` | `ERROR_IMAGE_TYPE_NOT_SUPPORTED` | `ERROR_IMAGE_TYPE_NOT_SUPPORTED` |
| Not valid base64 | `image_base64` | `ERROR_IMAGE_TYPE_NOT_SUPPORTED` | `ERROR_UPLOAD` |
| Missing or empty | `image_empty` | `ERROR_ZERO_CAPTCHA_FILESIZE` | `ERROR_ZERO_CAPTCHA_FILESIZE` |

A request with many problems lists at most 50 of them in `errors[]` (sorted by pointer); `detail` then ends with “and N more errors”. An image array over its maximum number of items is reported once at the array (`/params/images`), without checking each image.

The [sandbox](https://noptcha.com/docs/sandbox.md#limits) has additional, lower limits per organization. The 2captcha legacy API counts against the same limits; batch reads (`ids=`) count each task ID against the create rate of the key.

## Rate limit headers

`POST /v1/tasks` responses carry the current state of the create limit, in the structured form of the IETF draft *RateLimit header fields for HTTP* (not final yet; we will follow the RFC when it is published):

```http
RateLimit-Policy: "create";q=200;w=1
RateLimit: "create";r=153;t=1
```

`q` is the quota per window, `w` the window in seconds, `r` what remains, `t` the seconds until the quota is full again. Polls carry the `"poll"` policy only when over the limit; `GET /v1/usage` carries `"usage"`; `GET /v1/catalog` carries `"catalog"` only when over the limit.

## Handling 429 and 503

-   Wait for the number of seconds in `Retry-After`, then retry. Do not retry at once.
-   When a long poll returns `processing` immediately, wait a second before polling again.
-   In the compatibility API there is no HTTP 429; back off for a few seconds on `ERROR_NO_SLOT_AVAILABLE`.
-   Requests that were rejected did not create a task and were not charged.

## Deadlines

Each type has a deadline (60–180 seconds by default; see each [task type page](https://noptcha.com/docs/task-types.md) and `GET /v1/types`). A task not solved by then fails with `timeout` and is not charged.