Learn to Handle Errors in Your Integration

Table of contents

Tilled-Specific Server Errors
Tilled.js Error Codes
Tilled.js v1 Error Codes (Deprecated)

Learn about Tilled errors and how to handle them.

This page includes Tilled-specific server errors and Tilled.js console errors and solutions. Use it to troubleshoot your integration.

Tilled-Specific Server Errors

Error Code	Description	Solution
400 (Bad request)	Missing `tilled-account-id` header	Please specify an `account_id`.
401 (Unauthorized)	Invalid/missing `tilled-api-key` header	Verify that you are using the correct API key and that it has appropriate permissions for your request.
401 (Unauthorized)	`tilled-account-id` is not accessible (authorized) via `api_key.account_id` that was used for authentication	Provide an API key associated with the specified account.
403 (Forbidden)	Either the `tilled-account-id` is of a type that is incapable of making your request or your request is originating from a provider on our blocked list	Verify that your hosting provider is not on our blocked list. If so, please contact our team at integrations@tilled.com. If it is not on the list, reattempt this request with your partner `account_id`.
404 (Not found)	Invalid tilled-account-id header (not found in database)	Verify that you are using the correct `account_id`.

Tilled.js Error Codes

Display Message	Description	Solution
‘paymentRequest’ is required for form field type ‘paymentRequestButton’	The field was created with a `type` of `paymentRequestButton`, but the `paymentRequest` was not set in the forms `fieldOptions` parameter.	Set the paymentRequest attribute in your `form.createField` like so: `var prButton = form.createField('paymentRequestButton', { paymentRequest: paymentRequest, });` Refer to the PaymentRequest example in our docs for more information.
Unable to start Apple Pay session.	The merchant does not have the capabilities (i.e. does not support either the country, currency, or card network) to process this payment or Tilled was unable to initialize the ApplePaySession	Verify that the merchant is capable of processing the payment intent and that you have completed the steps to verify your domain.
No DOM Element found with id {selector}.	The selector provided in your `inject` method call does not exist in the DOM.	Double-check that you are passing the correct element id when attempting to inject your PaymentRequest button. Refer to our PaymentRequest example in our docs for more information.
selector + ‘ DOM Element must have a parent container’	The user attempted to inject an element that does not have a parent element.	Nest your PaymentRequest button element within a container element.
Field of type ‘${fieldType}’ is required	The build method failed because the necessary fields for the payment method’s `type` were not created	Verify that you created all the necessary fields with the createField method. Refer to the Form and Form Field section of our docs for more information.
Unhandled payment method type	The user attempted to confirm a payment intent with a `payment_method.type` that is not supported by Tilled.js	Verify that the payment intent’s `payment_method.type` matches one of the following: `card`, `ach_debit`, or `eft_debit`.
The payment intent client secret is required. e.g.`'tilled.confirmPayment(<here>, params)'`	The user did not specify a client secret in their call to the confirmPayment method	Pass a payment intent’s client secret into the call to the confirmPayment method.
`payment_method` is a required property. e.g. `'tilled.confirmPayment(secret, { payment_method: <here> })'`	The user did not specify the payment_method parameter in their call to the confirmPayment method.	Pass a `payment_method` parameter into the call to the confirmPayment method.
A `form` is required.	The user attempted to confirm a payment intent with the confirmPayment method without building a form object.	Verify that the form has been successfully built with the build method.
A `tilled.form()` is required prior to creating a payment method	The user attempted to create a payment method with the createPaymentMethod method without building a form object.	Verify that the form has been successfully initialized with the form method.
Field of type `${fieldType}` is not valid	The user entered a value that did not pass our form validation	Disable the submit button if the form is invalid. Refer to our Simple Payment Example for more information.
Expected `document.body` not to be null. Tilled.js requires a `<body>` element.	The user attempted to initialize a `Tilled` instance in an HTML page without a `<body>` element.	Verify that the page has a body element and add one as necessary.
Unauthorized: jwt malformed	The publishable key or account id is missing or invalid	Verify that you have specified valid a valid account id and publishable key when initializing a Tilled object instance.

Tilled.js v1 Error Codes (Deprecated)

Code	Display Message	Detailed Message	Description	Solution
9003	Invalid fields: `<card number \|\| cvv \|\| expiry date>`	Invalid fields: `<card number \|\| cvv \|\| expiry date>`	Tilled did not receive one or more of the following in the proper type: card number, cvv, expiry date .	Check to make sure you supplied the correct value with the proper type (string).
9023	There was an error (9023), please contact our support.	No container element was found using `${fieldName}` selector.	The selector you have used in your `inject` method call does not correspond to an element within the DOM.	Verify that the container element exists and the id matches the one used in the `inject` method call.
9024	There was an error (9024), please contact our support.	More than one container element was found using `${fieldName}` selector	The selector you have used in your `inject` method call corresponds to multiple elements within the DOM.	Verify that the container element you are attempting to inject possesses a unique id that matches the one used in the `inject` method call.
9025	There was an error (9025), please contact our support	The same container was found for both `${firstField}` and `${secondField}`	The same container was selected for multiple fields in your `inject` method calls.	Check to make sure you are passing the correct element ids in your `inject` method calls. You may need to create a new field element.
9028	There was an error (9028), please contact our support.	Failed to initialize Paysafe.js iframes.	The iframes used for the sensitive payment fields failed to initialize within 5 seconds. This could occur if the server that generates the HTML for the iframe is not available.	Try opening the page in a different browser or an incognito window. If the error persists, please contact integrations@tilled.com.
9029	There was an error (9029), please contact our support.	`${fieldName}` placeholder should be string.	The placeholder is of a type other than string.	Convert the value of the placeholder attribute to a string.