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.

Subscription & Usage Errors#

Subscription Inactive#

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#

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#

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#

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.

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, 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).

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#

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