top-blocks copy

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. If you have an issue that isn't covered here or on our Status page, please let us know.

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. Here are the Authentication error codes:

Error codeDescription or detailsMeaning and potential solutionHTTP status code
AUTHENTICATION_ERRORVariesThe access token is incorrect in your request.403 Forbidden
INVALID_AUTHORIZATIONVariesThe 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. Here are the Create error codes:

Error codeDescription or detailsMeaning and potential solutionHTTP status code
FONT_NOT_FOUNDNon 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 https://api.typeform.com/themes.404 Not Found
IMAGE_NOT_FOUNDImage with id {id} was not foundAn 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_IDNoneWe couldn't find the form_id specified in the request. Confirm that you're using the correct form_id.404 Not Found
PAYMENT_REQUIREDThe "{feature}" feature can not be used by this accountThe request includes a feature that requires a PRO or PRO+ account, 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_ERRORRequested 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_UNAVAILABLEVariesOur servers are too busy or taking too long to respond. Please try your request again later.503 Service Unavailable
THEME_NOT_FOUNDNon 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_ERRORVaries (see below)The payload is invalid. Check the specified field and correct the type value.400 Bad Request
{"code": "ADDITIONAL_PROPERTY", "field": "{field}", "description": "should NOT have additional properties", "in": "body"}The specified field is in the wrong object. Check the schema and move the specified field to the correct object in your request.400 Bad Request
{"code": "MAX_ITEMS", "field": "{field}", "description": "should NOT have more than {number} items", "in": "body"}The specified field has too many values listed. Check the specified field and reduce the number of values listed.400 Bad Request
{"code": "MAX_LENGTH", "field": "{field}", "description": "should NOT be longer than {number} characters", "in": "body"}A value in the specified field exceeds the maximum length. Check the specified field and reduce value lengths.400 Bad Request
{"code": "MIN_ITEMS", "field": "{field}", "description": "should NOT have less than {number} items", "in": "body"}The specified field has too few values listed. Check the specified field and add values to meet the minimum requirement.400 Bad Request
{"code": "MIN_LENGTH", "field": "{field}", "description": "should NOT be shorter than {number} characters", "in": "body"}A value in the specified field does not meet the minimum required length. Check the specified field and add to the value lengths.400 Bad Request
{"code": "NOT_ALLOWED_VALUE", "field": "{field}", "description": "should be equal to one of the allowed values", "in": "body"}The value is incorrect for a key-value pair in the specified field. Confirm that all values included in the specified field are valid.400 Bad Request
{"code": "PATTERN", "field": "{field}", "description": "should match the pattern", "in": "body"}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.400 Bad Request
{"code": "REQUIRED_PROPERTY", "field": "{field}", "description": "should have required property '{property}'", "in": "body"}The specified field is missing a required property. Check the specified field and add the missing required property.400 Bad Request
{"code": "UNKNOWN_FIELD_REFERENCE", "field": "{field}", "description": "Invalid field reference in '{property}'", "in": "body"}The specified field uses an invalid ref for another field. Check the specified field and correct the ref as needed.400 Bad Request
{"code": "WRONG_TYPE", "field": "{field}", "description": "should be {type}", "in": "body"}The type value is incorrect in the specified field. Check the specified field and correct the type value.400 Bad Request

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. Here are our Responses error codes:

Error codeDescription or detailsMeaning and potential solutionHTTP status code
NOT_EXISTING_IDNoneWe couldn't find the form_id specified in the request. Confirm that you're using the correct form_id.404 Not Found
SERVER_ERRORRequested 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_UNAVAILABLEVariesOur servers are too busy or taking too long to respond. Please try your request again later.503 Service Unavailable
UNAUTHORIZEDNoneThe 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.

If a webhook fails, Typeform will retry the request to your endpoint using the following rules:

  • If 410 Gone or 404 Not Found HTTP status is received, no retry is performed, and the webhook is disabled immediately.
  • If the 429 Too Many Requests, 408 Timeout, 503 Service Unavailable, or 423 Locked HTTP code is received, Typeform will retry the request to your endpoint every 2-3 minutes for 10 hours.
  • If any other HTTP code is received, Typeform will retry the request to your endpoint five times using a back-off mechanism after 5, 10, 20, 60, and 120 minutes.

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.

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.

If a webhook fails 100% of the time within 24 hours with more than 300 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 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.

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

import { useCallback } from 'react'
import { Widget } from '@typeform/embed-react'

function MyComponent() {
  const handleSubmit = useCallback(() => {
    // ...
  }, [])

  return <Widget id="<form-id>" onSubmit={handleSubmit} />
}