• 400 Bad request error
• 401 Unauthorized error
• 403 Forbidden error
• 404 Not found
• 422 Unprocessable entity
• On-premise Agent - No profile found
• NetSuite - 500 internal server error
• Job debug tracing
• Error notification emails
• Recipe design-time errors
• Job errors (recipe execution errors)
• Infinite Loops
• Rate limiting

400 Bad request error

The 400 Bad request error indicates that the server was unable to process an invalid request. This occurs if the request is malformed, contains invalid fields (or columns), or if the request violates any field constraints.

Solution

400 Bad request errors cover a wide range of errors that cannot be properly processed by the server. Try the following troubleshooting steps to identify the issue.

1. Check that field and column names are formatted properly. Ensure that you follow the naming convention (snake case or camel case) and that the names are case-sensitive.

2. Ensure that your record IDs are valid. If your input fields contain IDs of records that do not exist, it will cause the action to fail.

3. If you are sending a file, check if the file is too large.

4. Refresh the connection to retrieve a fresh connection token.

401 Unauthorized error

The 401 Unauthorized error indicates that your connection credentials are invalid. This can occur if the connection credentials were updated since you last used them to connect to AppConnect.

Solution

Reconnect your application to resolve this issue:

1. Navigate to the Connection.

2. Disconnect the connection and reconnect with the updated credentials.

403 Forbidden error

The 403 Forbidden error indicates that you do not have permission to access the data necessary to perform an action. For example, you have permission to access employee records, but not their salaries. If your recipe involves performing an action with the employee salaries, but AppConnect cannot access their salaries with your account permissions, the recipe will fail.

Solution

If this error occurs in the action, use network tracing to troubleshoot and identify the specific record that is causing the issue.

Since network tracing is not available for triggers, if the 403 Forbidden error occurs in the recipe trigger, build a recipe to identify the record that is causing the error.

404 Not found

The 404 Not found indicates that the record that you are trying to reach cannot be found. This can occur if you are passing an incorrect ID. For example, using the Insightly record ID to retrieve a NetSuite record.

Solution

Verify that the datapills are mapped to the correct fields.

1. Check that the record ID is valid for the applications (i.e. use an Insightly ID for an Insightly record).

2. Check that the record ID is valid for the object types (i.e. use a Customer Record ID for a customer object).

3. Check that the record has not been deleted.

422 Unprocessable entity

The 422 Unprocesable entity indicates that the action could not be processed properly due to invalid data provided. This occurs when there is a data conflict. For example, if you are trying to create a new user and the user email already exists, the server will return a 422 Unprocessable entity.

Solution

Verify that the input data provided is valid.

1. For a Create record action, check if there is already a record with a unique key (email, ID).

2. For an Update record action, check if the record exists. Otherwise, create a record.

3. Check that all reference IDs are valid. For example, when assigning an Insightly lead to a sales rep, there must be an existing sales rep.

4. Check if the field is required. If so, the field cannot be blank.

On-premise Agent - No profile found

The No profile found error indicates AppConnect cannot find a matching profile name in the target on-prem application. This is usually because of a mismatch between the profile name used in the connection setup and the connection profiles configured on the on-prem agent. This applies for all On-prem connections.

Solution

Verify that the credentials contained in the OPA config match the credentials provided in the connection setup.

1. Ensure that the following fields are correctly configured with the appropriate YAML syntax.

2. Check that the same profile name is used in the connection setup page.

NetSuite - 500 internal server error

During your workflow, if the target application fails to return a proper response, the recipe may encounter a 500 internal server error. When this happens, the error details provided may not be sufficient to debug the problem.

Solution: Get error details from 500 internal error

Use AppConnect's Monitor & Handle Errors block. Wrap the erroneous action in the Monitor block. This will provide more details about the error.

1. Insert the actions raised the 500 internal error in an Error monitoring block.

2. Run the job.

3. When the action fails, look into the On Error block to view the full error message.

Job debug tracing

Integration projects by their very nature are moderate to very complex involving multiple business systems. Connecting to and updating records in cloud applications like Insightly, Workday, and Netsuite is easy to do with an integration platform like AppConnect.

With varied use cases like employee onboarding (HR) or quote to cash (sales ops), many business systems and cloud applications like Workday, Netsuite, ServiceNow and others will typically be part of the automation. This poses a challenge to developers and analysts who are building recipes but run into errors like HTTP 404 Not Found. Having no further information makes it difficult to debug and troubleshoot.

Overview

The job debug tracing makes it easy to see detailed HTTP requests and responses for each action line. With details like HTTP URL, request and response headers, request payload, and the response, there's a lot of detailed information for the developer and analyst to uncover the root cause of the problem.

For each action line in the recipe, job debug tracing provides

• HTTP URL to which the request was made

• HTTP request headers

• HTTP response headers

• HTTP request payload

• HTTP response

Enabling and disabling job debug tracing

To enable job debug tracing, go to Account Settings > Recipe Preferences. Check Enable network trace and click Save.

To disable job debug tracing, go to Account Settings > Recipe Preferences. Uncheck Enable network trace and click Save.

Debug tracing privilege

By default, the debug tracing privilege is available to users with Admin roles or users who are owners of the AppConnect account.

You may also assign Debug Trace privilege by creating a custom role. Once the custom role is created, you can assign the custom role to any developer or analyst in the team. Make sure to Save the assignment of the privilege to the custom role.

Sensitive data

We know data security is very important to our customers. We also understand you need controls so that sensitive data is only visible to authorized users. That's why we have created two layers of control to give you maximum flexibility.

• First, you can completely turn off debug tracing at the account level so no user can view debug trace.

• Second, you can control which user has the privilege to see the debug trace data.

Viewing job debug tracing

Debug or network tracing is available when:

• A test job is run while in the recipe edit mode. You can view the network tracing during development when the recipe is tested in the TEST JOBS tab.

• A job is repeated. Jobs that are completed, whether successfully or failed, can be repeated to view the network tracing.

Test recipe

Network tracing gives you the tools to make recipes more robust by detecting and avoiding errors early on. During development, you can test the recipe by going to the TEST JOBS tab and clicking the Test button. Testing a recipe validates the functionality and implementation of the recipe. The test job provides the network tracing in the Debug tab.

Developers can view not only the input and output but also the network trace of the HTTP calls made for the action. You can review and validate the information in HTTP headers, requests, and responses flowing between the recipe action and the end application.

You can view the HTTP network tracing including headers, request, and the response from the API calls made to the application when the action is executed. The screenshots show the headers, requests, and responses sent and received in the HTTP request.

Jobs in error

Follow the steps below to generate and view the debug trace for a recipe whose job is in error.

In this example, the Update incident in ServiceNow has jobs in error.

To view the debug trace, you must repeat the job.

Repeat job

To generate debug trace, you need to repeat the job.

In the job details page for a job, click Repeat job.

Job debug tracing example

If you have seen HTTP 404 Not Found or 400 Bad Request or 403 Forbidden and wanted more details about the error, now you can with the job debug tracing.

Here's an example scenario, where the update to an incident table in ServiceNow fails with the 404 Not Found error. And how job debug tracing enables you to quickly and efficiently understand the root cause of the error by providing you more details.

Viewing debug trace

Once the job is repeated, the latest repeat of the job shows the debug trace in the Debug tab of the action line.

Click on the HTTP request line to expand and get more information on the request.

HTTP Headers, Request, and Response

To view headers sent as part of the request, click on the Headers tab.

The Payload tab shows the request payload sent with the request.

To see the response returned by the HTTP request, click on Response tab.

FAQ

How long is the tracing data available for?

Tracing data is available for 1 day from the time it was generated by repeating a job. If you want to access the data after 1 day, you can repeat the job to generate the debug tracing.

List of connectors not supported

• Active Directory

• ADP

• Ariba

• AWS Cognito

• AWS SNS

• Email

• Etapestry

• Expensify

• FTP

• Google Drive

• JDBC

• JMS

• Kafka

• MSSQL

• MYSQL

• Netsuite

• On-prem Files

• Oracle

• Oracle Fusion

• Redshift

• SFTP

• SMS

• Snowflake

• SOAP

Error notification emails

Jobs may encounter errors when trying to fetch trigger events, or when trying to carry out an action. This section briefly explains trigger errors and actions errors, and covers AppConnect's error notification policy and how it handles recipes that run into consecutive errors.

Trigger errors

Trigger errors occur when the recipe tries to retrieve trigger events by polling the trigger app. The recipe might fail to retrieve trigger events in the following cases:

• When the connection becomes invalid and the recipe is unable to connect successfully to the app. Usually results in an unauthorized error message.

• When the connected user does not have the right permissions to retrieve the trigger events. Usually results in an unauthorized error message.

• When the recipe makes an API call that is somehow broken, e.g. due to schema changes in the app that wasn't reflected in the recipe via a schema refresh.

• When the recipe makes an API call that times out while waiting for the trigger events. This is usually transient, i.e. the API server might be experiencing temporary downtime.

• When the trigger filters put in place are logically incorrect, e.g. when a null value is checked against an integer, etc. In such cases, the trigger filters will need to be fixed before the recipe can run properly.

Trigger warnings

When a trigger error is met, the recipe will surface a trigger warning, but continue to poll for trigger events. No failed jobs will be reflected on the jobs report, because no jobs were created - the recipe was unable to even retrieve any trigger events to be processed.

In the following case, a trigger warning was raised because the schema recorded in the recipe did not match the schema in the app. The warning suggests refreshing the schema as a way to resolve the trigger error, and further details of the error can be seen when expanded.

Recipes stopped by AppConnect

When the recipe has encountered 60 trigger errors, it will be stopped by AppConnect automatically under the assumption that there's a critical, non-transient error with the trigger configuration or connection that needs to be fixed.

An email notification will be sent to the AppConnect account owner when a recipe is stopped due to 60 trigger errors.

Action errors

Action errors occur when the recipe tries to carry out an action, e.g. trying to create a new lead record, or trying to search for a specific account in Insightly, and fails to do so. Actions might fail in the following cases:

• An invalid input was provided to the app, e.g. a number was expected for an invoice subtotal amount but a string (text) was passed in instead, or the values "High", "Medium" and "Low" were expected values, but the value "Normal" was passed in instead

• An input was required, but when the job was carried out, a null value was passed into the field

In cases of action errors, the Input tab shows the data passed into the action, while the Output tab usually shows the error message. You can usually figure out what's wrong by checking the data in the input tab.

Recipes stopped by AppConnect

When the recipe encounters 5 successive action errors that are identified by AppConnect as an unauthorized error, rate limit error or schema error, the recipe will be stopped by AppConnect automatically under the assumption that there's a critical, non-transient error with the action configuration or connection that needs to be fixed.

Error notifications

AppConnect sends email notifications to the AppConnect account owner when error occurs.

Notification policy

There are certain rules that determine when an email is sent:

• Email is sent when a recipe encounters a certain type of error for the first time, e.g. unauthorized, timeout. Subsequent errors of the same type that occur for that same recipe in the following 1 hour will not generate an email notification.

• Email is sent whenever a recipe is stopped by AppConnect.

Recipe design-time errors

Recipe design-time errors refer to errors that are caught while building a recipe. These errors typically show up when you click on recipe test or recipe start, and prevent you from testing or starting the recipe until they are resolved.

This is because recipes with design-time errors will definitely result in job errors if ran. We go through common design-time errors in this section.

Missing required input fields at design-time

Triggers and actions typically need configuration to be useful in a recipe. For example, to update a Zendesk organization, we need, at a minimum, the ID of the organization to update. Therefore, that's a required field in the recipe.

If the recipe detects that a required input field is lacking values or datapills, it will raise a design-time error and refuse to start until the input field has been filled with a value or a datapill.

You will be able to see the items needed to be fixed in the step details drawer.

Once you fix a specific error, the item will get crossed off your checklist.

Design-time formula errors

Every input field (except for list input fields) can be toggled between text and formula mode. When in formula mode, errors in formula syntax will raise design-time errors.

Common design-time formula errors are:

• misspelt formulas (such as the above)

• lack of proper spacing between formulas and operators (e.g. having 2 whitespaces instead of 1)

• formula syntax errors (e.g. using curly braces { } instead of square brackets [ ])

• symbols in the wrong format (e.g. when copying formulas and symbols from word processors like OpenOffice and Microsoft Word, these programs may format symbols like ", ' and { } differently and cause the AppConnect formula editor to not recognize these symbols)

Invalid datapills

Datapills can become invalid when their source is missing, e.g. if the trigger or action that the datapill comes from is changed, or if the field gets deleted from the app (e.g. if the custom field Customer subscription plan in Insightly object Organization gets deleted in Insightly, that datapill will become invalid for use in AppConnect). Invalid datapills will turn red.

In the following example, design-time errors due to invalid datapills are raised when the Insightly trigger is changed.

To resolve issues with invalid datapills, you need to replace these pills with valid datapills or values.

Unavailable fields

Sometimes you may receive a design time error if the recipe uses data fields that are not available in your app. In such cases, you will either have to add the fields in your app and perform a refresh schema in the recipe editor or remove the unavailable fields in your recipe.

App connection errors

App connections can become invalid due to several reasons:

• app credentials were changed and the connection was not updated correspondingly in AppConnect

• connected user doesn't have the right set of permissions to read/write selected records

• permissions of the connected user were changed to a reduced scope

In such cases, reconnecting or verifying that the connected user has permissions to read/write records used in the recipes should work to re-establish the connection.

Job errors (recipe execution errors)

Job errors, also known as recipe execution errors, usually occur when a trigger event has been found, and a job is being processed, therefore typically showing up as recipe job errors. An exception to this is trigger errors, which occur when the recipe fails to retrieve any trigger events and therefore does not create any jobs.

Trigger errors

Trigger errors occur when the recipe tries to retrieve trigger events by polling the trigger app, but fails to fetch trigger events successfully. As no trigger event data was retrieved, the recipe does not create a job in the first place.

The following table details the various reasons for trigger errors, and how we can resolve them.

Run-time formula errors

Every input field (except for list input fields) can be toggled between text and formula mode. Formulas that didn't throw any design-time errors when the recipe was started can still throw run-time errors during a job, when actual data is being processed by the recipe.

Some of the reasons for run-time errors are:

• datapill had no value and was nil, and the formula acting on it doesn't work on null values

• formula tries to execute invalid operation that was not caught at design time, e.g. dividing a number by a string (text)

• formula was used on a datapill of the wrong data type, e.g. using true? formula on an array datapill

Missing required fields at run-time

Triggers and actions typically need configuration to be useful in a recipe. For example, to update a Zendesk organization, we need, at a minimum, the ID of the organization to update. Therefore, that's a required field in the recipe.

Required input fields that didn't throw any design-time errors when the recipe was started, because the field had a datapill as input, can still throw run-time errors if the datapill had no value during the job, when actual data is being processed by the recipe.

If we toggle to the input tab in this job details screen, we see that the Channel input field has an empty string.

If we look at the action mapping, we see that this action didn't throw a design-time error because it had a datapill in it, but it threw an error when the job was being processed as that datapill had no value.

Timeouts

Whenever the recipe carries out the trigger (to request for a list of trigger events from the trigger app), or an action (to carry out the action in the action app), AppConnect is sending a request to the app and waiting for a response back.

Some reasons for a job timeout would be:

• the app might take too long to respond to AppConnect, and the trigger or action will raise a timeout error after it has waited for a certain amount of time

• the job might be taking too long to carry out, and the job raises a timeout error

Passing wrong datatypes into input fields

In some cases, the datapill used for an input field has a data type that is not expected by the input field, e.g. we pass in a string ("12.50") into a input field expecting a number (12.50). This might not be caught at design-time, but the app we provide this string to might throw an error when it receives unexpected data types.

Infinite Loops

What are infinite loops and when do they occur?

Infinite loops are logic errors that cause a recipe to run continuously because an action in the recipe is also triggering the recipe again.

Infinite loops occur most commonly when the recipe is performing a bi-directional sync (ie. when there is more than 1 application and data moves from Application A to Application B and back to A)

Infinite loops may also occur if you have multiple recipes running at once and a similar issue occurs where one recipe is updating another that is triggered by an update in an object.

Signs the recipe is in an infinite loop

Recipes may be in an infinite loop if:

• There is an unexpectedly high transaction count

• The recipe is triggered when there are no new trigger events in the applications

• There are many duplicates of an object in applications that was created by a recipe

How to prevent infinite loops

Trigger Filters

In order to stop the re-triggering of recipes, implement filters in the trigger.

Best Practices

Creating Custom Fields

Create fields in the connected applications that are meant for identifying jobs synced by AppConnect.

Thus, it is not advisable to use a commonly used field for these purposes, as they may be filled in by mistake and cause that job to be filtered out in the trigger.

Use specific labels like: "Synced by AppConnect" or "QuickBooks Invoice URL" to prevent mistakes like these from happening.

Rate limiting

Most APIs have a cap on the number of API calls you can make within a certain period. These limits usually differ by app.

In cases whereby the rate limits may have been reached, the particular trigger or action will throw an error in AppConnect when made. In such cases, the error is typically explicit about being a rate limit error.

To remedy such errors, you might want to look into optimizing your recipes to make minimal calls (by reducing the number of actions done with that particular app). If it occurs frequently, you might want to increase your API rate limits for that app.