> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://typeform.ferndocs.com/troubleshooting/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://typeform.ferndocs.com/_mcp/server. # Troubleshooting > **Note:** This page contains both a page directory (above) and the landing page content (below). The page directory is generated for agent use and does not appear on the landing page. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://typeform.ferndocs.com/troubleshooting/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://typeform.ferndocs.com/_mcp/server. # Troubleshooting and Errors Error handling depends on which part of the Developer Platform you're using. We'll post any service interruptions — and updates when they're resolved — on our [Status page](http://status.typeform.com). If you have an issue that isn't covered here or on our Status page, please [let us know](https://successteam.typeform.com/to/rGVAYs). ## Authentication If your request causes an authentication error, the response will contain an error object. The error object includes information to help you resolve the problem. The information included in the error object varies depending on the error, but all error objects include a **`code`**, which is a short, readable key to help you identify the error. ### Authentication Error Codes | Error code | Description or details | Meaning and potential solution | HTTP status code | | --------------------- | ---------------------- | ---------------------------------------------- | ---------------- | | AUTHENTICATION_ERROR | Varies | The access token is incorrect in your request. | 403 Forbidden | | INVALID_AUTHORIZATION | Varies | The access token is incorrect in your request. | 403 Forbidden | ## Create API If your request causes an error in the Create API, the response will contain an error object. The error object includes information to help you resolve the problem. Request validation runs in stages, so your request may return errors in stages — for example, you'll see schema-related errors first, before errors related to incorrect field references. The information included in the error object varies depending on the error, but all error objects include a **`code`**, which is a short, readable key to help you identify the error. ### Create API Error Codes | Error code | Description or details | Meaning and potential solution | HTTP status code | | ------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | FONT_NOT_FOUND | Non existing font '\{name}' | You specified an invalid font for your theme. Confirm that you're using one of the valid fonts listed for the `POST /themes` endpoint. | 404 Not Found | | IMAGE_NOT_FOUND | Image with id \{id} was not found | An `image_id` specified in the form request does not exist in your Typeform account. Use the correct `image_id` for images that already exist in your Typeform account. | 404 Not Found | | NOT_EXISTING_ID | None | We couldn't find the `form_id` specified in the request. Confirm that you're using the correct `form_id`. | 404 Not Found | | PAYMENT_REQUIRED | The "\{feature}" feature can not be used by this account | The request includes a feature that requires a [PRO or PRO+ account](https://www.typeform.com/pricing/), such as Hidden Fields, Logic Jumps, and custom Thank You screens. To use the feature, register for the appropriate account level. | 402 Payment Required | | SERVER_ERROR | Requested account does not exist (account_id: \{id}). | There's a problem with the server right now. Please try your request again later. | 500 Internal Server Error | | SERVICE_UNAVAILABLE | Varies | Our servers are too busy or taking too long to respond. Please try your request again later. | 503 Service Unavailable | | THEME_NOT_FOUND | Non existing theme with id \{id} | The `theme_id` specified in the form request does not exist in your Typeform account. Use the correct `theme_id` for a theme that exists in your account. If you do not specify a theme in your request, the default theme is automatically applied. | 404 Not Found | | VALIDATION_ERROR | Varies (see below) | The payload is invalid. Check the specified field and correct the `type` value. | 400 Bad Request | ### Validation Error Details | Code | Field | Description | Meaning | | ----------------------- | --------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ADDITIONAL_PROPERTY | `{field}` | should NOT have additional properties | The specified field is in the wrong object. Check the schema and move the specified field to the correct object in your request. | | MAX_ITEMS | `{field}` | should NOT have more than \{number} items | The specified field has too many values listed. Check the specified field and reduce the number of values listed. | | MAX_LENGTH | `{field}` | should NOT be longer than \{number} characters | A value in the specified field exceeds the maximum length. Check the specified field and reduce value lengths. | | MIN_ITEMS | `{field}` | should NOT have less than \{number} items | The specified field has too few values listed. Check the specified field and add values to meet the minimum requirement. | | MIN_LENGTH | `{field}` | should NOT be shorter than \{number} characters | A value in the specified field does not meet the minimum required length. Check the specified field and add to the value lengths. | | NOT_ALLOWED_VALUE | `{field}` | should be equal to one of the allowed values | The value is incorrect for a key-value pair in the specified field. Confirm that all values included in the specified field are valid. | | PATTERN | `{field}` | should match the pattern | The key-value pair pattern is incorrect in the specified field. Check the specified field and reorganize key-value pairs to follow the field's pattern according to the example request. | | REQUIRED_PROPERTY | `{field}` | should have required property '\{property}' | The specified field is missing a required property. Check the specified field and add the missing required property. | | UNKNOWN_FIELD_REFERENCE | `{field}` | Invalid field reference in '\{property}' | The specified field uses an invalid `ref` for another field. Check the specified field and correct the `ref` as needed. | | WRONG_TYPE | `{field}` | should be \{type} | The `type` value is incorrect in the specified field. Check the specified field and correct the `type` value. | ## Responses API If your request causes an error in the Responses API, the response will contain an error object. The error object includes information to help you resolve the problem. The information included in the error object varies depending on the error, but all error objects include a **`code`**, which is a short, readable key to help you identify the error. ### Responses API Error Codes | Error code | Description or details | Meaning and potential solution | HTTP status code | | ------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------- | | NOT_EXISTING_ID | None | We couldn't find the `form_id` specified in the request. Confirm that you're using the correct `form_id`. | 404 Not Found | | SERVER_ERROR | Requested account does not exist (account_id: \{id}). | There's a problem with the server right now. Please try your request again later. | 500 Internal Server Error | | SERVICE_UNAVAILABLE | Varies | Our servers are too busy or taking too long to respond. Please try your request again later. | 503 Service Unavailable | | UNAUTHORIZED | None | The access token is incorrect in your request. | 401 Unauthorized | ## Webhooks API For the Webhooks API, we determine successful requests by checking the HTTP status code in the response. Your webhook should send a `2XX` HTTP status code back to let Typeform know that you received the webhook data. Any response except a `2XX` code, including no response, tells Typeform that your webhook is failing. ### Webhook Retry Behavior If a webhook fails, Typeform will retry the request to your endpoint using the following rules: * **`410 Gone` or `404 Not Found`**: No retry is performed, and the webhook is disabled immediately. * **`429 Too Many Requests`, `408 Timeout`, `503 Service Unavailable`, or `423 Locked`**: Typeform will retry the request every 2-3 minutes for 10 hours. * **Any other HTTP code**: Typeform will retry the request five times using a back-off mechanism after 5 min, 10 min, 20 min, 1 hr, 2 hrs, 3 hrs, and 4 hrs. ### Webhook Failure Notifications When webhook requests are failing, you'll notice a lack of responses to your webhook URL or web application, and you will receive an email notification. > **Note** > > **Webhooks created with the Webhooks API are not listed in the typeform's workspace.** For webhooks you create in your typeform's workspace, you'll be able to see the last 50 delivery attempts under *Configure* > *Webhooks* > *Recent Requests*. Even if Typeform's requests to your webhook are failing, your respondents will be able to submit completed typeform responses, and we will store their responses safely on Typeform's servers. If your webhook fails, you can log in to your Typeform account to view responses or use our Responses API to retrieve responses for the period of webhook failure. > **Warning** > > If a webhook fails 100% of the time within 24 hours with more than 300 delivery attempts or within 5 minutes with 100 delivery attempts, we will disable it, and you will receive a notification. ## Embed SDK Here are solutions to common Embed issues. ### An element in my page is overlapping the embedded typeform For the modal modes and mobile devices (which always display typeforms as modals), we use a default [z-index](https://developer.mozilla.org/en-US/docs/Web/CSS/z-index) of 10,000. Set the z-indexes for elements on your page according to whether you want them to appear over or under the typeform modal. [See README for details](https://github.com/Typeform/embed/tree/main/packages/embed#positioning-and-overlapping) ### Transparency is not applied on mobile devices Embed functions do not apply transparency on modals, and all embedded typeforms behave like a modal on mobile devices. ### Customized typeform with a small embed height doesn't display correctly Although there's no minimum height requirement for embedded typeforms, we recommend a height of at least 350px. Your typeform might not display correctly at smaller heights. ### Problem with a custom embed Custom embeds often cause issues that detract from the user experience. We do not support or recommend custom embeds. ### Embed with React keeps reloading When using our library for React [@typeform/embed-react](https://www.npmjs.com/package/@typeform/embed-react), you might experience that your embedded typeform keeps reloading. In most cases, this is due to passing some callback that's not memoized. We recommend always using `useCallback` to prevent that. ```tsx import { useCallback } from 'react' import { Widget } from '@typeform/embed-react' function MyComponent() { const handleSubmit = useCallback(() => { // ... }, []) return } ``` ## Need More Help? * **[Status Page](http://status.typeform.com)** - Check for service interruptions * **[Contact Support](https://successteam.typeform.com/to/rGVAYs)** - Report issues not covered here * **[Community Forums](https://community.typeform.com)** - Ask the community * **[Help Center](https://www.typeform.com/help)** - Search our knowledge base