Troubleshooting and errors

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.

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:

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:

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:

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 min, 10 min, 20 min, 1 hr, 2 hrs, 3 hrs, and 4 hrs.

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 or within 5 minutes with 100 delivery attempts, we will disable it, and you will receive a notification.

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} />
}