ScreenshotAPI.net API Key Invalid: How to Fix the Authentication Error

A ScreenshotAPI.net HTTP 401 does not necessarily mean the API key is malformed. Start with the response error identifier: the documented token_required error means the token parameter is missing, while subscription_inactive is a separate 401 condition. Then inspect the request that was actually sent and compare its token with the current key in your ScreenshotAPI Dashboard.

The examples below show the documented token parameter. Replace YOUR_TOKEN with your active key and keep it private. ScreenshotAPI’s official Errors documentation, Getting Started guide, and Help page describe the error identifiers, token setup, and key rotation.

1. Identify the actual error before changing the key

Read both the HTTP status and the response body or error identifier. A status code alone is not enough to distinguish a missing token from account state.

Response	Meaning	Next action
`401 token_required`	The authentication token is missing from the request.	Send the `token` parameter and confirm it is non-empty.
`401 subscription_inactive`	The subscription is inactive. This is not evidence by itself that the token is malformed.	Review the account’s subscription status.
`402 payment_required`	A billing-related condition.	Review billing and account status rather than repeatedly changing the token.
`403 trial_expired`	The trial has expired.	Review the account’s plan or subscription options.
`403 screenshots_limit_reached`	The documented usage quota has been reached.	Check usage and plan limits.
`429 screenshots_limit_reached`	The documented requests-per-minute limit has been reached.	Reduce request rate and retry in accordance with your workflow.

These names and statuses come from ScreenshotAPI.net’s published error table. The reviewed documentation does not specify a distinct error identifier or detailed response body for every possible invalid-token case, so do not infer more than the response actually says.

2. Confirm the token in the outgoing request

Open the integration’s request configuration, not just its source template. Verify the final request includes a token parameter.
Check that the value is present, not blank, and not truncated by a secret manager, environment variable, or deployment setting.
Confirm it belongs to the expected ScreenshotAPI account. Retrieve the key from the account’s Dashboard, as described in the Help page.
Compare the request shape with the vendor’s Getting Started examples or Query Builder output. Avoid sharing the actual key while debugging.

Use a secret store or environment variable in applications. Do not put a live key in a public repository, ticket, screenshot, command transcript, or application log. If a key has been exposed, rotate it and update all callers.

3. Make a minimal request

First use a simple request to isolate authentication from optional capture settings. The examples use the documented token parameter and a URL to capture.

cURL

curl -G "https://shot.screenshotapi.net/screenshot" \
  --data-urlencode "token=YOUR_TOKEN" \
  --data-urlencode "url=https://example.com" \
  -o screenshot.png

Python

import os
import requests

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

Node.js

const token = process.env.SCREENSHOTAPI_TOKEN;
if (!token) throw new Error("Set SCREENSHOTAPI_TOKEN first");

const query = new URLSearchParams({
  token,
  url: "https://example.com",
});
const response = await fetch(
  `https://shot.screenshotapi.net/screenshot?${query}`
);
if (!response.ok) {
  const body = await response.text();
  throw new Error(`ScreenshotAPI returned ${response.status}: ${body}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import("node:fs/promises").then(({ writeFile }) =>
  writeFile("screenshot.png", image)
);

These examples illustrate the vendor’s token-based request shape; use the endpoint and any required parameters shown in your own ScreenshotAPI Dashboard or current integration configuration. The documentation identifies the token parameter but does not establish that every optional capture parameter is needed for authentication.

4. Replace a rotated key everywhere

ScreenshotAPI’s Help page says the Dashboard’s Roll API Key action issues a fresh key and revokes access from the previous key. If someone rolled the key, the old value will no longer be the current credential.

Retrieve the current key from the Dashboard.
Update every place that could still call the API: environment variables, deployed secrets, scheduled tasks, automation modules, local development configuration, and background workers.
Restart or redeploy processes that load secrets only at startup.
Make one minimal request and confirm the new deployment is sending the replacement key.

Do not roll a key just because a response is 401: first distinguish token_required from subscription_inactive and check whether the outgoing request actually contains the current token.

5. Troubleshoot common authentication failures

Symptom	Likely cause	Fix
`token_required` even though a key exists in your code	The request builder omitted the parameter, used a different parameter name, or read an empty variable.	Inspect the final URL or request parameters with the token value redacted; send the documented `token` field.
401 after a deployment or secret update	The process may still have the old value, or the deployment secret was not updated in the environment handling this caller.	Check the running environment’s secret name and value presence, then restart or redeploy as needed.
401 after key rotation	A caller is still using the revoked key.	Replace the old key across all callers and restart long-running jobs.
401 with the current Dashboard key	The response may indicate inactive subscription, or the request may not be sending the key you expect.	Check the response identifier, verify the actual outgoing request, and review account status.
402, 403, or 429 mistaken for an invalid key	Billing, trial, quota, or request-rate condition.	Use the matching error identifier and status from the table above; changing credentials does not address those conditions.
Works locally but fails in an automation platform	The platform may have a separate credential field or stale saved configuration.	Update that specific connection or module and verify the configured parameter name and current secret.

If the active Dashboard key is definitely being sent and the request still fails, retain the exact status, response identifier/body, endpoint, timestamp, and a redacted request for support. Never send the key itself. The public documentation reviewed here does not define a more specific invalid-token diagnostic to substitute for the server response.

6. Keep integrations reliable and control usage

Keep secrets out of code. Read the token from a runtime secret or environment variable and limit access to the services that need it.
Make rotation operational. Record which deployments and automations use the credential so a rotation can be applied everywhere before old callers create confusing failures.
Log diagnosis safely. Record status, error identifier, endpoint, and timestamp, but redact query strings or headers that contain credentials.
Handle errors by class. A missing-token error should stop until configuration is corrected; quota and rate errors need usage or pacing changes; subscription and billing errors need account review.
Set a sensible client timeout. Screenshot generation can take longer than a simple metadata request. Choose a timeout suitable for your workflow and handle timeouts separately from authentication errors.

Cost and limits depend on the account’s ScreenshotAPI plan and usage. The cited error documentation identifies quota and rate-limit failures but does not provide a pricing figure in the material used for this guide. Check the vendor’s current account and plan details rather than treating a 401 as a usage charge problem.

7. Or skip the browser setup

If your goal is simply to capture a page and your current integration is blocked, ScreenshotNeo is a website screenshot API and MCP server for developers. Its API accepts one GET request for a URL and 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 accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

FAQ

Does every ScreenshotAPI.net 401 mean the key is invalid?

No. The published error table includes both token_required for a missing token and subscription_inactive for an inactive subscription, both with status 401.

Where do I get my ScreenshotAPI.net token?

ScreenshotAPI’s Help page directs users to the Dashboard. Its Getting Started guide shows the token supplied in the request.

What happens when I roll the API key?

The Help page says rolling issues a fresh key and revokes the previous one. Update every integration that used the old key.

Should I send support my key to prove the error?

No. Send the status, error response, endpoint, time, and a redacted request. Keep the credential secret.