Why Is Microlink Returning a 429 Error for Screenshot Requests?

Microlink returns HTTP 429 when a request exceeds the applicable rate limit; its API overview associates the response with error code ERATE. Check the response body and the x-rate-limit-limit, x-rate-limit-remaining, and x-rate-limit-reset headers. If the allowance is exhausted, wait until the indicated reset or use an eligible Pro key with the Pro endpoint. Microlink documents 25 requests per day on its free plan. Microlink API overview

What a 429 means for a screenshot request

HTTP 429 means the service is refusing a request because the applicable request limit has been exceeded. For Microlink, look for ERATE in the response body to confirm that this is the documented rate-limit condition. A 429 alone does not prove which plan or quota applied to a particular request: check the endpoint, authentication, response body, and headers.

Microlink enables screenshot generation with its screenshot parameter. A successful response can include screenshot data and a CDN asset URL; delivery options include returning JSON metadata or serving the image directly with embed: 'screenshot.url'. These response-format choices do not increase the request quota. Screenshot parameter guide · Embed and delivery guide

Diagnose the response step by step

Read the HTTP status and response body. Confirm status 429 and check whether the error code is ERATE. Preserve the response body while debugging; it helps distinguish a rate limit from other request failures.
Record all three rate-limit headers. x-rate-limit-limit reports the applicable limit, x-rate-limit-remaining reports the remaining allowance, and x-rate-limit-reset gives the reset time as UTC epoch seconds. Use the values on the failed response instead of assuming a fixed reset time.
Verify the endpoint matches the plan. Microlink documents the free endpoint at api.microlink.io and the Pro endpoint at pro.microlink.io. Pro authentication uses the x-api-key header on the Pro endpoint. A Pro key sent to the free endpoint is not the documented Pro configuration.
Choose the applicable remedy. If the free allowance is spent, wait until the reset indicated by the response, or use a Pro key with the Pro endpoint if the account has Pro access.

Runnable examples for inspecting a 429

The examples below send a screenshot request and print the status, rate-limit headers, and response body. Replace https://example.com with the target page. For the free endpoint, omit the Pro key. To use Pro, change the hostname to pro.microlink.io and send your key in x-api-key.

cURL

curl -sS -D response-headers.txt -o response-body.json \
  -G 'https://api.microlink.io' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'screenshot=true'

cat response-headers.txt
cat response-body.json

For Pro, use the Pro hostname and add the header:

curl -sS -D response-headers.txt -o response-body.json \
  -G 'https://pro.microlink.io' \
  -H 'x-api-key: YOUR_MICROLINK_PRO_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'screenshot=true'

Python

import os
import requests

endpoint = 'https://api.microlink.io'
headers = {}

# For Pro, use this endpoint and header instead:
# endpoint = 'https://pro.microlink.io'
# headers['x-api-key'] = os.environ['MICROLINK_PRO_KEY']

response = requests.get(
    endpoint,
    params={'url': 'https://example.com', 'screenshot': 'true'},
    headers=headers,
    timeout=60,
)

print('HTTP status:', response.status_code)
for name in (
    'x-rate-limit-limit',
    'x-rate-limit-remaining',
    'x-rate-limit-reset',
):
    print(f'{name}:', response.headers.get(name))
print(response.text)

if response.status_code == 429:
    response.raise_for_status()

Node.js

const endpoint = new URL('https://api.microlink.io');
endpoint.searchParams.set('url', 'https://example.com');
endpoint.searchParams.set('screenshot', 'true');

const headers = {};
// For Pro, use https://pro.microlink.io and uncomment:
// headers['x-api-key'] = process.env.MICROLINK_PRO_KEY;

const response = await fetch(endpoint, { headers });
console.log('HTTP status:', response.status);
for (const name of [
  'x-rate-limit-limit',
  'x-rate-limit-remaining',
  'x-rate-limit-reset',
]) {
  console.log(`${name}:`, response.headers.get(name));
}
console.log(await response.text());

Keep API keys out of source control and client-side code. Read the response headers before retrying: repeatedly sending the same request while the remaining count is zero does not resolve the limit.

Choose what to do after confirming the limit

Situation	Next step
The headers show no remaining allowance and reset is in the future	Pause requests until the UTC epoch time in `x-rate-limit-reset`.
The workload cannot wait and the account has Pro access	Call `pro.microlink.io` with the Pro token in `x-api-key`.
A Pro key is present but the request still appears to use the free service	Check that the request hostname is `pro.microlink.io` and that the key is in the header.
The request only needs a screenshot	Consider `meta: false` to skip metadata extraction and improve speed. This does not raise the limit or bypass a 429.

Screenshot-only performance and reliability

Microlink’s screenshot guide says setting meta: false skips metadata extraction and is usually the largest speed improvement when you only need the screenshot. Use it to avoid work your application does not need, not as a rate-limit workaround. A faster request still counts against the applicable allowance.

For reliable batch jobs, track the reset header and remaining count, queue work when the allowance is depleted, and retry only after reset or after switching to an eligible Pro configuration. Avoid tight retry loops: they cannot create additional quota and can waste time and requests. The sources cited here document the free daily allowance and higher Pro quota, but do not establish an exact Pro limit; inspect the applicable account and response rather than assuming a number.

Common causes and fixes

Free daily allowance used: Microlink’s overview states the free plan allows 25 requests per day. Wait for the response’s reset time or use Pro access.
Wrong host for a Pro key: Pro credentials belong on pro.microlink.io, sent as x-api-key. Correct both the host and header.
Retry loop continues through 429s: Stop retries until the indicated reset. Add queueing or backoff based on the reset header.
Metadata work is unnecessary: Set meta: false for screenshot-only calls to reduce processing time. Do not expect it to change quota.
The response is not actually a rate limit: Check the body for ERATE, the status, and headers. The available documentation does not diagnose individual requests, so retain these details when investigating an account-specific issue.

Or skip the browser setup

ScreenshotNeo is a website screenshot API with an MCP server for developers and AI agents. One GET request returns an image or PDF; see the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo removes cookie banners, popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Does setting `meta: false` fix a 429?

No. It can speed up screenshot-only requests by skipping metadata extraction, but it does not increase quota or bypass a rate limit.

How do I convert the reset header into a date?

x-rate-limit-reset is UTC epoch seconds. In JavaScript, for a header value named reset, use new Date(Number(reset) * 1000).toISOString().

Does a 429 prove that my Pro key is invalid?

No. Check the endpoint and whether the Pro key is sent as x-api-key to pro.microlink.io, then use the response body and rate-limit headers to diagnose the request.