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.

Authentication Error Codes

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

Validation Error Details

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

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.

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.

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

Need More Help?

• Status Page - Check for service interruptions
• Contact Support - Report issues not covered here
• Community Forums - Ask the community
• Help Center - Search our knowledge base