Skip to content
NoptchaNoptcha Docs

Rate limits and quotas

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

Section titled “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 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

Section titled “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 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

Section titled “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):

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

Section titled “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

Section titled “Deadlines”

Each type has a deadline (60–180 seconds by default; see each task type page and GET /v1/types). A task not solved by then fails with timeout and is not charged.