# Error Reference

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

- **URL**: https://orshot.com/docs/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

| 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:```js
headers: {
  "Authorization": "Bearer YOUR_API_KEY"
}
```Get your API key from Workspace Settings → API Keys. See [Get API Key](https://orshot.com/docs/quick-start/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](https://orshot.com/docs/definitions/render-usage) to understand consumption)
- Upgrade your plan or wait for the billing cycle to reset
- Enable [Overage Renders](https://orshot.com/docs/misc/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](https://orshot.com/pricing) 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:```js
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](https://orshot.com/docs/definitions/template-id).

---

### 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](https://orshot.com/templates) 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:```js
body: JSON.stringify({
  templateId: "your-template-id",
  modifications: {
    title: "My Title",
    // ... other modifications
  },
});
```Learn more about [Modifications](https://orshot.com/docs/definitions/modifications).

---

## Response Format Errors

### Unsupported Response Format

| Code    | `400`                                                                                               |
| ------- | --------------------------------------------------------------------------------------------------- |
| Message | `Response format not supported. Supported formats: png, jpeg, jpg, webp, avif, 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`, `avif`
- **Documents:** `pdf`
- **Videos:** `mp4`, `webm`, `gif`

See [Response Format](https://orshot.com/docs/definitions/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](https://orshot.com/docs/definitions/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). This also applies to templates with [flowing content](https://orshot.com/docs/orshot-studio/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

---

## 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).```js
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/WebP/AVIF

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

**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

| 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:```js
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:```js
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](https://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:

1. Check the [Quick Start Guide](https://orshot.com/docs/quick-start) for basic setup
2. Review [API Reference](https://orshot.com/docs/api-reference) for correct request formats
3. Reach out at [orshot.com/contact](https://orshot.com/contact)