Error Reference

Common API errors, what they mean, and how to fix them

A quick reference guide to help you understand and resolve errors when using the Orshot API.

Authentication Errors

Authorization Header Missing

Code	`403`
Message	`Access Forbidden: Authorization header is missing in the request`

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

Code	`403`
Message	`Access Forbidden: API Key is missing in the request`

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

Code	`400`
Message	`Access Forbidden: 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

Code	`400`
Message	`Access Forbidden: The API Key or User ID do not exist`

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

Code	`401`
Message	`Access Forbidden: 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

Code	`401`
Message	`Access Forbidden: 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.

Subscription & Usage Errors

Subscription Inactive

Code	`403`
Message	`Subscription inactive or you've consumed all requests`

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

Fix:

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

Video on Free Plan

Code	`403`
Message	`Video generation is available only on paid plans`

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

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

Partner Limit Reached

Code	`429`
Message	`Partner monthly render limit reached (X/Y). Limit resets next month.`

Why it happens: Your partner sandbox workspace has exceeded its monthly allocation.

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

Invalid Partner Account

Code	`403`
Message	`This sandbox workspace is not associated with a valid 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

Code	`400`
Message	`'templateId' is missing in the request body`

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

Code	`403`
Message	`Studio template with ID 'X' 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

Code	`400`
Message	`templateId not found. Please double check the 'templateId' value`

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

Fix: Check the Templates Library for valid template IDs.

Modifications Missing

Code	`400`
Message	`Modifications for 'X' is missing in the request`

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.

Response Format Errors

Unsupported Response Format

Code	`400`
Message	`Response format not supported. Supported formats: png, jpeg, jpg, webp, pdf, mp4, webm, gif`

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

Fix: Use one of the supported formats:

Images: png, jpeg, jpg, webp
Documents: pdf
Videos: mp4, webm, gif

See Response Format for details.

Unsupported Response Type

Code	`400`
Message	`Response type not supported. Supported types: binary, url, base64`

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

Code	`400`
Message	`Binary response type is not supported for multi-page templates unless format is PDF`

Why it happens: You can't get binary output for multi-page templates (except PDFs).

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

Page Errors

Invalid Page Numbers

Code	`400`
Message	`Invalid page numbers in includePages: X. Valid range is 1-Y.`

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)

Code	`400`
Message	`Invalid page number 'X'. Page number must be a positive integer.`

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)

Code	`400`
Message	`"templateId" is missing in the 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

Code	`400`
Message	`"sign" parameter is missing in the URL`

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

Code	`404`
Message	`Sign does not match for this dynamic URL`

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

Code	`404`
Message	`Dynamic URL with ID 'X' 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

Code	`404`
Message	`Dynamic URL for templateID 'X' is inactive. Enable it from Template playground page to start rendering`

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

Code	`403`
Message	`This dynamic URL has reached its maximum render limit. Increase Max Renders in the Template Playground for more renders`

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

Code	`403`
Message	`Dynamic URL has expired. Please update the expiration time in the Template playground to continue rendering`

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

Code	`400`
Message	`Video generation is 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

Code	`400`
Message	`Invalid quality value 'X'. Quality must be between 1 and 100.`

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

Code	`400`
Message	`Quality parameter is only supported for JPEG/JPG formats. Current format: X`

Why it happens: The quality parameter only works with JPEG output.

Fix: Either:

Remove the quality parameter, or
Set responseFormat=jpg or responseFormat=jpeg

Signed URL Errors

Signed URL Inactive

Code	`401`
Message	`This signed URL is inactive. Please activate it from the dashboard`

Why it happens: The signed URL has been deactivated.

Fix: Reactivate the signed URL from your dashboard.

Signed URL Expired

Code	`401`
Message	`Signed URL has expired. Please create a new signed URL.`

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

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

Invalid Signature

Code	`401`
Message	`Invalid signature. Please create a new signed URL.`

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

Code	`400`
Message	`"templateId", "signature", "modifications" or "id" is missing in the URL`

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

Code	`400`
Message	`Missing or invalid 'websiteUrl' value. Please provide a valid url for 'websiteUrl' modification`

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

Code	`400`
Message	`Missing 'inputImage' value. Please provide a valid url for 'inputImage' modification`

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

Code	`402`
Message	`Insufficient AI credits` or errors containing `AI generation`

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

Code	`500`
Message	`Orshot Server Error(details). Reach out at orshot.com/contact for support`

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

Code	`500`
Message	`Orshot Server Error: Failed to generate screenshots for multi-page template`

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

Code	`500`
Message	`Failed to store page X: error details`

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:

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

All Set? Let's Start Automating

Get Your API Key →

Image, PDF and Video Generation via API
Canva like editor with AI and smart features
No-Code Integrations (Zapier, Make, n8n etc.)
Embed Orshot Studio in your app
Start Free. No credit card required. Cancel anytime.