How to Fix a ScreenshotAPI.net API Key Error

If ScreenshotAPI.net returns an API key error, first check that your request includes the current key from your account dashboard in the token query parameter. Then read the response error code: token_required means the token is missing, while subscription, payment, trial, quota, and rate-limit errors need account or usage fixes rather than a different key. If you roll the key, replace it everywhere your integrations use it because the old key is revoked.

1. Check the request token

ScreenshotAPI.net documents screenshot requests in this form:

GET https://shot.screenshotapi.net/v3/screenshot?token=YOUR_API_KEY&url=https%3A%2F%2Fexample.com

Replace YOUR_API_KEY with the current key shown in your dashboard. Do not send the literal placeholder. Confirm that the final request contains a token parameter, that the copied value is complete, and that the target URL is URL-encoded when you construct the query yourself.

The documented token_required error is HTTP 401 and means the authentication token is missing from the request. A key can appear in your application configuration but still be absent from the actual outgoing URL, so inspect the request your code sends.

cURL

curl --get 'https://shot.screenshotapi.net/v3/screenshot' \
  --data-urlencode 'token=YOUR_API_KEY' \
  --data-urlencode 'url=https://example.com' \
  --output screenshot.png

Python

import requests

response = requests.get(
    "https://shot.screenshotapi.net/v3/screenshot",
    params={
        "token": "YOUR_API_KEY",
        "url": "https://example.com",
    },
    timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
    image_file.write(response.content)

Using a parameter dictionary lets the HTTP library encode the query string, including the destination URL. If the request fails, inspect the HTTP status and provider error response before saving the body as an image.

Node.js

const params = new URLSearchParams({
  token: 'YOUR_API_KEY',
  url: 'https://example.com',
});

const response = await fetch(
  `https://shot.screenshotapi.net/v3/screenshot?${params}`
);

if (!response.ok) {
  const body = await response.text();
  throw new Error(`ScreenshotAPI.net returned ${response.status}: ${body}`);
}

const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) =>
  writeFile('screenshot.png', image)
);

Keep the key on the server side. Avoid putting it in browser JavaScript, public repositories, shared logs, or screenshots of configuration. The provider’s terms make the account holder responsible for credential secrecy and security.

2. Get the current key from the dashboard

Sign in to ScreenshotAPI.net and open the account dashboard.
Copy the API key displayed there.
Update the value used by your application, environment variable, deployment secret, or automation platform.
Inspect a newly generated request and confirm its token parameter uses that value.

The provider says its Query Builder can automatically add the key when you are logged in. Still inspect the generated request: a key added in the browser’s builder does not automatically update a separate server, scheduled job, or deployment configuration.

3. Read the error code before changing credentials

Not every authorization-looking response means the API key is wrong. ScreenshotAPI.net lists distinct errors for authentication, account status, payment, trial, quota, and request rate. Use the response code and body to choose the fix.

Response	What it indicates	What to do
`401 token_required`	The request is missing its authentication token.	Add `token` and verify it is the current dashboard key.
`401 subscription_inactive`	The subscription is inactive.	Check the account’s subscription status.
`402 payment_required`	Payment or quota status requires attention.	Review billing and usage details in the account.
`403 trial_expired`	The trial has expired.	Review the account plan and trial status.
`403 screenshots_limit_reached`	The screenshot quota has been exceeded.	Check plan limits and current usage.
`429 screenshots_limit_reached`	The documented rate-per-minute limit has been reached.	Reduce request frequency and retry later in accordance with your usage needs.

These codes are listed separately in the provider’s official error documentation. A 401 can therefore mean either a missing token or an inactive subscription; check the specific error name rather than relying on the status alone.

4. Rotate a key that is exposed or stale

If a key may have been exposed, or you cannot establish which copy is current, rotate it in ScreenshotAPI.net. Its help instructions say to use Roll API Key in the dashboard Settings card. Rolling issues a new key and revokes the old one.

Use the dashboard’s Roll API Key control.
Save the new key in your secret manager or protected environment configuration.
Update every integration that used the old key: application servers, deployment secrets, scheduled jobs, and automation workflows.
Redeploy or restart affected services if they read secrets only at startup.
Check each integration’s outgoing request and confirm it uses the new key.

Do not keep retrying with the revoked key. If you rotate before updating all integrations, those still holding the former value will fail authentication. The provider’s help page covers where to find and roll the key; its terms describe the account holder’s responsibility for credential security.

5. Troubleshoot common implementation mistakes

Symptom	Likely cause	Fix
`token_required` even though a key exists in configuration	The request builder never added the value to the outgoing `token` parameter.	Inspect the complete outgoing URL or request parameters; add `token` explicitly.
401 or 403 after copying a key	The request may contain a stale, truncated, or placeholder value.	Copy the current dashboard value and compare it with the configured secret. Recheck the generated query.
401 with `subscription_inactive`	The account subscription is inactive; this is not the documented missing-token error.	Resolve the subscription status in the account.
402 or quota-related 403	Billing, plan quota, or trial status prevents the request.	Review billing, trial state, plan, and usage before changing the key.
429 with `screenshots_limit_reached`	The rate-per-minute limit has been reached.	Reduce the request rate, avoid immediate repeated retries, and retry later.
Requests fail after a key roll	One or more integrations still use the revoked key.	Update every stored secret and redeploy or restart services that cache configuration.
Key appears in a public repository or client-side code	The credential is accessible to people who should not use it.	Roll the key, remove the exposed copy, and keep the replacement in protected server-side configuration.

6. Keep credentials reliable and private

Store the key in an environment-specific secret store rather than committing it to source control.
Use the same secret-management path for local development, staging, and production, with the correct account key in each environment.
When an authentication failure begins after deployment, check whether the deployed secret changed and whether the service was restarted or redeployed to load it.
Do not log full request URLs if they include the token query parameter. Redact credentials from diagnostic output.
After rotation, verify all consumers, including infrequent scheduled tasks that may not run during the immediate deployment.

These practices follow from the provider’s guidance that credentials must remain secret and that rolling a key revokes its predecessor. They also make failures easier to isolate: the request, account state, and deployed secret can be checked independently.

7. Or skip the browser setup

If your actual goal is to get a website screenshot and you do not want to manage browser capture infrastructure, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF. See the ScreenshotNeo API docs.

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

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
An MCP server lets AI agents, including Claude, Cursor, and other MCP clients, use screenshot tools.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Where do I find my ScreenshotAPI.net API key?

Does every 401 mean my key is wrong?

No. The provider documents both token_required and subscription_inactive as 401 errors. Read the error name in the response.

Will my old key work after I roll it?

No. Rolling the key revokes the old key, so update all integrations to the newly issued value.

Can I put the token in frontend JavaScript?

Keep it private. A credential embedded in code delivered to a browser is exposed to its users; use a server-side request and protected configuration instead.

Sources

ScreenshotAPI.net Docs: Errors — documented status codes and error definitions.
ScreenshotAPI.net Help — dashboard key location, key rotation, and request format.
ScreenshotAPI.net: Save Website Screenshots to Google Drive with Make.com — token-related 401/403 troubleshooting.
ScreenshotAPI.net Terms of Service — credential security and usage limits.
ScreenshotAPI.net Docs: Query Builder — automatic key inclusion when logged in.