Why Does Browshot Return a 403 Error for My Screenshot Request?

A Browshot 403 does not identify one universal cause. Browshot’s general API documentation says malformed requests receive HTTP 403, while its simple API response section describes HTTP 400 for invalid requests and notes that an invalid key may be a cause. Check which endpoint you called, then inspect the status, response body, and X-Error header before changing your request. Browshot API documentation

What a Browshot 403 tells you

Browshot’s general API documentation states: “If the request is malformed, the server replies with a 403 error.” Its simple API response section gives different guidance: an invalid request returns HTTP 400, and an invalid key may be one cause. Those descriptions are endpoint-specific; they do not establish that every 403 means an incorrect key.

For a useful diagnosis, record the exact endpoint and examine the complete response. The simple API documentation says the error description is available in the X-Error header. Screenshot-create examples also show JSON error bodies, including Invalid key and Not enough credits. The documentation does not assign every example error a specific HTTP status.

Step-by-step troubleshooting

1. Identify the endpoint. Note whether the request went to /api/v1/simple, /api/v1/screenshot/create, or another endpoint. The documented status behavior differs by context, so do not diagnose from the status alone.
2. Confirm the API key is present and correct. Browshot requires an API key and says it is displayed in the dashboard. Replace any example placeholder, check for accidental whitespace or truncation, and make sure the request sends the key in the location expected by that endpoint. Never paste the key into public logs or support requests.
3. Check required parameters and their values. For /api/v1/screenshot/create, Browshot lists url and instance_id as required. Check spelling, URL encoding, and values against the endpoint documentation. A malformed request is associated with 403 in the general API description, but the docs do not provide a complete status mapping for each invalid parameter.
4. Read both headers and body. Save the HTTP status, response body, and relevant headers. Look for X-Error on simple API responses and JSON error details on screenshot-create responses. These messages can distinguish a key problem from a request validation or balance issue.
5. Check the balance for private or shared instances. Browshot says these instances require a positive balance. Its examples include a Not enough credits error, but the documentation does not say that this error necessarily uses HTTP 403.
6. Follow redirects when using curl. A screenshot may still be in progress and represented by a 302 redirect. Browshot’s curl instructions use -L to follow redirects. A 302 is a separate response to handle; the docs do not say that failing to follow one causes a 403.

Capture and inspect the response with curl

Use the exact endpoint and parameter names from your request. For a simple API request, this example preserves response headers and body so you can inspect the status and X-Error. Confirm the simple endpoint’s required query parameters in Browshot’s documentation before running it.

curl -sS -D response-headers.txt -o response-body.txt \
  -G "https://api.browshot.com/api/v1/simple" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com"

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

Do not share the saved files without removing the API key and any sensitive request data. For a screenshot-create request, use its documented url and instance_id parameters and the authentication format specified for that endpoint. Browshot’s endpoint documentation is the authority for the exact request shape.

Common errors and fixes

What you see	What to check	What to do
HTTP 403	The endpoint and request shape	Check whether the endpoint’s documentation associates malformed requests with 403; validate required parameters and inspect the full response.
HTTP 400 on the simple API	Invalid request details and X-Error	Read the header and verify the key and parameters. The simple API documentation describes invalid requests as 400.
Invalid key	Missing, placeholder, mistyped, or incorrectly supplied key	Copy the intended key from the Browshot dashboard and send it in the documented authentication field.
Not enough credits	Account balance and instance type	Check the balance; private and shared instances require a positive balance. Do not assume this message always corresponds to 403.
HTTP 302 or a redirect response	Whether the screenshot is still being generated and whether the client follows redirects	For curl, use -L as in Browshot’s command-line guidance.

When the cause is still unclear

Send Browshot support a concise, sanitized diagnostic record:

• The endpoint path and HTTP method.
• The HTTP status and response body.
• The relevant response headers, including X-Error when present.
• Request parameter names and non-sensitive values, with the API key removed.
• Whether the request used a private or shared instance, if applicable.

Never include the API key itself. Since the published documentation gives different status descriptions in different contexts, this evidence is more useful than reporting only “403.”

Or skip the browser setup

If your goal is to get a screenshot without diagnosing a capture environment, ScreenshotNeo returns an image or PDF from one API request. Its API and MCP server are for developers and AI agents; see the ScreenshotNeo API documentation for request options.

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,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An 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. Sign up for 1,000 free screenshots a month, no card required.

FAQ

Does a 403 prove my Browshot API key is wrong?

No. Browshot documents malformed requests as a possible source of 403, while its simple API section describes invalid requests as 400 and says an invalid key may be a cause. Check the endpoint and error details.

Does insufficient credit always return 403?

The documentation shows a Not enough credits error and requires a positive balance for private or shared instances, but it does not specify that this error always has status 403.

What should I include in a support request?

Include the endpoint, sanitized parameters, status, response body, and relevant headers. Remove the API key first.