invalid_format

The output format in the request is not one the API can produce. Nothing was rendered. Change the value and send the request again; retrying the same value fails the same way. This page is part of the error code reference.

Example response

{
  "error": {
    "type": "validation_error",
    "code": "invalid_format",
    "message": "Unsupported output format 'jpg'",
    "param": "output.format",
    "retryable": false,
    "docs": "https://docs.renderscreenshot.com/errors/invalid_format"
  },
  "request_id": "req_abc123"
}

Accepted values

Values are lowercase. See output options and response formats.

Where the format goes

The parameter has a different place in each request style. Putting it in the wrong place is a common mistake when you move code from GET to POST.

Common causes

• jpg. It is the usual file extension, but the API value is jpeg.
• A MIME type. image/png instead of png, often passed through from an Accept header or an upload form.
• A file extension with its dot or in capitals. .PNG from a file name.
• A format the API does not produce, such as gif, svg, bmp or tiff. Capture as PNG and convert it yourself if you need one of these.

How to fix it

1. Read error.message to see the exact value that was sent.
2. Use one of the four values in the table above.
3. If the value comes from users or file names, normalize it in your code before the request.
4. After a successful request, check the response Content-Type to confirm the format you received.

This function maps common spellings to the documented values and rejects the rest with a clear message, before any request leaves your app:

// format.mjs (Node 22+): map what users type to the documented output.format values.
const FORMATS = new Set(['png', 'jpeg', 'webp', 'pdf']);
const ALIASES = {
  jpg: 'jpeg',
  'image/png': 'png',
  'image/jpeg': 'jpeg',
  'image/webp': 'webp',
  'application/pdf': 'pdf',
};

export function toOutputFormat(input = 'png') {
  const value = String(input).trim().toLowerCase().replace(/^\./, '');
  const format = ALIASES[value] ?? value;
  if (!FORMATS.has(format)) {
    throw new RangeError(`Unsupported format "${input}". Use one of: ${[...FORMATS].join(', ')}`);
  }
  return format;
}

// Example: a user picked ".JPG" in your UI.
const API = process.env.RS_BASE_URL ?? 'https://api.renderscreenshot.com';
const res = await fetch(`${API}/v1/screenshot`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    output: { format: toOutputFormat('.JPG'), quality: 85 },
  }),
});
if (!res.ok) throw new Error(JSON.stringify(await res.json()));
console.log(res.headers.get('content-type')); // image/jpeg

With the Node SDK, pass the normalized value to TakeOptions.format(), and treat a 400 as a bug to fix, not a reason to retry:

import { Client, TakeOptions, RenderScreenshotError } from 'renderscreenshot';
import { toOutputFormat } from './format-lib.mjs'; // the function above, without the example request

const client = new Client(process.env.RS_API_KEY);

try {
  const image = await client.take(
    TakeOptions.url('https://example.com').format(toOutputFormat('jpg')).quality(85)
  );
  console.log(`${image.length} bytes`);
} catch (error) {
  if (error instanceof RenderScreenshotError && error.httpStatus === 400) {
    console.error('Request rejected with HTTP 400. Check output.format.'); // do not retry
    process.exitCode = 1;
  } else {
    throw error;
  }
}

Tested on 2026-10-15 with Node 22.18 and renderscreenshot 1.1.0 for Node, against a local mock. PNG, image/webp, jpg and .JPG normalized correctly; gif and avif were rejected before the request; a raw jpg sent to the mock returned the envelope above.

Related

• Output options for format, quality and transparent.
• invalid_parameter for values that are out of range.