Error Reference

A quick reference for understanding and resolving errors from the Orshot API. Each error includes the HTTP code, message, why it happens, and how to fix it.

Authentication Errors#

Authorization Header Missing#

Why it happens: Your API request doesn't include the required Authorization header.

Fix: Add the header to your request:

headers: {
  "Authorization": "Bearer YOUR_API_KEY"
}

Get your API key from Workspace Settings → API Keys. See Get API Key for setup instructions.

API Key Missing#

Why it happens: The Authorization header exists but doesn't contain a valid API key after "Bearer ".

Fix: Ensure the format is Bearer YOUR_API_KEY (with a space after "Bearer").

Invalid API Key#

Why it happens: The API key doesn't exist or has been revoked.

Fix: Generate a new API key from Workspace Settings → API Keys.

Invalid API Key or User ID#

Why it happens: Your API key isn't linked to a valid user account.

Fix: Double-check your API key or generate a new one from your dashboard.

OAuth Token Errors#

OAuth Token Expired#

Why it happens: Your OAuth access token has expired (tokens are valid for 15 minutes).

Fix: Use the refresh token to obtain a new access token, or re-authenticate via the OAuth device flow.

Invalid OAuth Token#

Why it happens: The OAuth token doesn't exist, has been revoked, or is malformed.

Fix: Re-authenticate via the OAuth device flow to obtain a new token.

OAuth Insufficient Scope#

Why it happens: The OAuth token is valid but was granted without the scope this endpoint needs. Rendering requires render:generate; other endpoints require their own scopes.

Fix: Re-authorize the app requesting the missing scope, then retry with the new token. Scopes are granted at authorization time, so an existing token cannot gain one.

App in Development Mode#

Why it happens: The developer application behind this token has not been approved for public use yet, so it only serves its owner and the test users listed on it.

Fix: Use the developer's own account or a listed test user while building. To serve everyone, submit the app for review from the developer application settings.

Subscription & Usage Errors#

Subscription Inactive#

Why it happens: Your subscription has expired, or you've used all your credits for the billing period.

Fix:

• Check your usage at Billing & Usage (see Credit Usage to understand consumption)
• Upgrade your plan or wait for the billing cycle to reset
• Enable Overage Credits to keep rendering beyond limits

Video on Free Plan#

Why it happens: You're trying to generate video output (MP4, WebM, MOV, MKV, GIF) on a Free plan.

Fix: Upgrade to a paid plan to unlock video generation.

Partner Limit Reached#

Why it happens: Your partner sandbox workspace has exceeded its monthly credit allocation. The API message reports the limit in renders — 2 renders = 1 credit — so the X/Y values shown are render counts.

Fix: Wait for the monthly reset or contact your partner account manager.

Invalid Partner Account#

Why it happens: The sandbox workspace isn't properly linked to a partner.

Fix: Contact Orshot support to verify your partner account setup.

Template Errors#

Template ID Missing#

Why it happens: Your request doesn't include a templateId.

Fix: Add the template ID to your request body:

body: JSON.stringify({
  templateId: "your-template-id",
  modifications: { ... }
})

Find your template ID in the Template Playground or when viewing a template. Learn more about Template IDs.

Template Not Found#

Why it happens: The template ID doesn't exist in your workspace.

Fix:

• Verify the template ID is correct
• Make sure the template belongs to your workspace
• Check your templates

Library Template Not Found#

Why it happens: The library template ID doesn't match any available template.

Fix: Check the Templates Library for valid template IDs.

Modifications Missing#

Why it happens: The modifications object is missing from your request.

Fix: Include modifications in your request body:

body: JSON.stringify({
  templateId: "your-template-id",
  modifications: {
    title: "My Title",
    // ... other modifications
  },
});

Learn more about Modifications.

Request Body Errors#

Invalid JSON Request Body#

Why it happens: The request body could not be parsed as JSON. Common causes: trailing commas, single quotes instead of double quotes, or a raw template expression pasted into the body.

Fix: Send a valid JSON body with Content-Type: application/json. If you build the body by hand in an automation tool, prefer the tool's JSON or key-value fields over a free-text body.

Request Body Too Large#

Why it happens: The request body exceeds the 10mb limit, usually because of large base64-encoded images inline in modifications.

Fix: Host large images and pass their URL instead of inlining base64 data.

Invalid PDF Options#

Why it happens: A value in pdfOptions is outside the accepted range. The checked fields are margin (pixel values only), rangeFrom and rangeTo (positive integers), colorMode ("rgb" or "cmyk"), imageFormat ("auto" or "jpeg"), imageQuality (1 to 100), and maxImageDpi (0 to 2400).

Fix: Correct the field named in the message. See PDF Options for every accepted value.

Render Warnings#

Studio render requests are inspected against the template before rendering. Problems with modification content never block the render: the render succeeds exactly as before, and a warnings array rides along so you can catch silently broken automations (a typo'd key, an unevaluated n8n expression) without losing output.

Where warnings appear:

• JSON responses (response.type of url or base64) include a top-level warnings array when there is at least one warning:

{
  "data": { "content": "https://storage.orshot.com/...", "type": "url", "format": "png" },
  "warnings": [
    {
      "title": "Unknown modification 'titel' was ignored. No parameter named 'titel' exists on this template. Did you mean 'title'? Valid keys: title, description, photo.",
      "details": ""
    }
  ]
}

• Binary responses carry an X-Orshot-Warnings header (a JSON-encoded array, capped at 5 entries) since there is no JSON body to extend.
• Render logs always record the warnings, so you can debug from the dashboard even for dynamic URL image tags where headers and bodies are not inspectable.

The warning types:

Unknown Modification Key#

Unknown modification 'X' was ignored. Did you mean 'Y'?...

A key in modifications doesn't match any parameter on the template, so it did nothing. Common causes: a typo, a parameter renamed or deleted after you built the integration, or a payload meant for a different template. The warning suggests the closest matching key and lists valid keys (the 5 closest on large templates). Fetch the current parameter list from the template's modifications endpoint or the Template Playground and update your mapping.

Page Prefix Problems#

'page7@heading' was ignored: it targets page 7, but this template has 2 pages...

A pageN@key modification points at a page that doesn't exist, the prefix is malformed (pageX@heading), the parameter lives on a different page (the warning names the right one), or a multi-page template received a bare key that needs a page prefix to apply. Use pageN@key with a page number the template has, e.g. page1@heading. See Multi-Page Templates.

Unevaluated Template Expression#

The value for 'X' looks like an unevaluated n8n/Make expression ({{ ... }})...

A value like {{ $('Previous Node').item.json }} reached the API as literal text and rendered as-is. Your automation tool sent the expression itself instead of its result, usually because the field is in fixed-value mode. In n8n, switch the field from Fixed to Expression so the variable resolves before sending; Make behaves the same with {{1.field}} mappings. See the n8n integration guide. Simple placeholders like {{name}} (inline text parameters) and {{_page_number}} (flowing content) never trigger this warning.

Non-Scalar Value#

The value for 'X' should be a string, number, or boolean; received an array...

Modification values should be scalars; objects and arrays get stringified into the design ([object Object] or comma-joined text). Map the specific field you want, e.g. item.json.title instead of item.json. Exception: X.promptReferences accepts an array of image URLs.

Image Value#

'X' is an image parameter but "..." does not look like an image URL...

The template marks this parameter as an image source, but the value can't load as an image (e.g. plain text). Pass an http(s) URL or a data: URI. An empty string keeps the template's stored image; use X.prompt to generate the image with AI instead.

Modifications Not an Object#

'modifications' should be a JSON object mapping parameter keys to values...

modifications was sent as something other than a JSON object, most often a JSON-encoded string ("{\"title\": \"Hello\"}") or an array. It was ignored and the template rendered with its default values. Send the object itself, not a string.

Response Format Errors#

Unsupported Response Format#

Why it happens: You specified an invalid response.format value.

Fix: Use one of the supported formats:

• Images: png, jpeg, jpg, webp, avif
• Documents: pdf
• Videos: mp4, webm, mov, mkv, gif

See Response Format for details.

Unsupported Response Type#

Why it happens: You specified an invalid response.type value.

Fix: Use one of:

• binary - Raw file data (best for direct downloads)
• url - Hosted URL to the rendered file
• base64 - Base64-encoded string

See Response Type for details.

Binary Not Supported for Multi-Page#

Why it happens: You can't get binary output for multi-page templates (except PDFs). This also applies to templates with flowing content that generates overflow pages.

Fix: Either:

• Use response.type: "url" or "base64" for multi-page templates
• Use response.format: "pdf" to get a single binary PDF
• Add response.includePages: [1] to render only one page as binary

Video/GIF Requires URL Response Type#

Why it happens: You requested response.type: "base64" or "binary" with a video or GIF response.format (mp4, webm, gif, mov, mkv). These formats only support response.type: "url".

Fix: Set response.type: "url" when rendering video or GIF output.

Smart Resize Errors#

Invalid Render Size#

Why it happens: Returned for an invalid Smart Resize request — either response.size (or response.width/height) can't be resolved, or response.extraSizes is combined with an unsupported option. The exact message names the cause:

• size isn't a known preset slug or a "WIDTHxHEIGHT" string; or width/height aren't integers between 10 and 5000px (and must be sent together).
• extraSizes with a response.type other than url or base64 (a binary stream can only return one file).
• extraSizes on a template with flowing (auto-expanding) elements.
• extraSizes with a PDF or video format — it currently supports image formats only (png, jpg, webp, avif).
• The request would produce more than 50 extra outputs (pages × extra sizes) — each extra size is billed like a page.

Fix:

• Pass size as a preset slug (e.g. instagram-story) or "1080x1920"; or send width + height together (10–5000px).
• For extraSizes, use response.type url or base64, an image format, and a non-flow template.
• Keep pages × extraSizes at 50 or fewer per call — reduce the sizes or pages, or split into multiple requests.

See Render from Studio Template → Smart Resize for the full reference.

Page Errors#

Invalid Page Numbers#

Why it happens: You specified page numbers that don't exist in the template.

Fix: Check your template's page count and use valid page numbers (1-based).

response: {
  includePages: [1, 2, 3]; // Only existing page numbers
}

Invalid Page Number (Dynamic URL)#

Why it happens: The page query parameter isn't a valid positive integer.

Fix: Use a positive integer for the page parameter: ?page=1

Dynamic URL Errors#

Template ID Missing (Dynamic URL)#

Why it happens: The dynamic URL is missing the required templateId query parameter.

Fix: Include templateId in your URL: ?templateId=your-template-id&sign=...

Sign Parameter Missing#

Why it happens: Dynamic URLs require a sign parameter for security.

Fix: Copy the complete dynamic URL from the Template Playground, which includes the sign parameter.

Sign Does Not Match#

Why it happens: The signature doesn't match the template, possibly because URL parameters were modified.

Fix: Regenerate the dynamic URL from the Template Playground.

Dynamic URL Not Found#

Why it happens: The template ID doesn't have a dynamic URL configured.

Fix: Enable dynamic URL for your template in the Template Playground settings.

Dynamic URL Inactive#

Why it happens: The dynamic URL has been disabled.

Fix: Go to your template's Playground page and toggle the dynamic URL to active.

Dynamic URL Render Limit Reached#

Why it happens: You've hit the maximum render count set for this dynamic URL.

Fix: Increase the "Max Renders" limit in your template's Playground settings.

Dynamic URL Expired#

Why it happens: The dynamic URL's validity period has passed.

Fix: Update the expiration date in your template's Playground settings.

Video Not Supported for Dynamic URLs#

Why it happens: Dynamic URLs don't support video output formats.

Fix: Use the POST API endpoint (/v1/studio/render) for video generation instead.

Quality Parameter Errors#

Invalid Quality Value#

Why it happens: The quality parameter must be an integer from 1-100.

Fix: Use a valid quality value: ?quality=85

Quality Only for JPEG/WebP/AVIF#

Why it happens: The quality parameter only works with JPEG, WebP, and AVIF output.

Fix: Either:

• Remove the quality parameter, or
• Set responseFormat to jpg, jpeg, webp, or avif

Signed URL Errors#

Signed URL Inactive#

Why it happens: The signed URL has been deactivated.

Fix: Reactivate the signed URL from your dashboard.

Signed URL Expired#

Why it happens: The signed URL's expiration time has passed.

Fix: Generate a new signed URL with a longer expiration time.

Invalid Signature#

Why it happens: The URL signature doesn't match, possibly due to parameter tampering.

Fix: Generate a fresh signed URL from the API or dashboard.

Missing Signed URL Parameters#

Why it happens: Required query parameters are missing from the signed URL.

Fix: Make sure all required parameters are included when generating the signed URL.

Website Screenshot Errors#

Invalid Website URL#

Why it happens: The websiteUrl modification is missing or not a valid URL.

Fix: Provide a valid URL:

modifications: {
  websiteUrl: "https://example.com";
}

Background Removal Errors#

Input Image Missing#

Why it happens: The inputImage modification is required for background removal.

Fix: Provide a valid image URL:

modifications: {
  inputImage: "https://example.com/image.png";
}

AI Generation Errors#

AI Credits Exhausted#

Why it happens: Your workspace has run out of AI credits for AI-powered features.

Fix: Purchase more AI credits from your Billing Settings.

Server Errors#

General Server Error#

Why it happens: An unexpected error occurred on our servers.

Fix:

• Retry the request after a few seconds
• If it persists, contact us at orshot.com/contact with the error details

Screenshot Generation Failed#

Why it happens: The server couldn't generate the requested images.

Fix:

• Check that your template and modifications are valid
• Retry the request
• Contact support if the issue continues

Storage Error#

Why it happens: The rendered image couldn't be saved to storage.

Fix: This is usually temporary. Retry the request or contact support.

Need Help?#

If you're still stuck:

1. Check the Quick Start Guide for basic setup
2. Review API Reference for correct request formats
3. Reach out at orshot.com/contact