Autotask integration: System Logs and troubleshooting

Introduction

This article explains how to use the System Logs page to monitor integration activity, interpret log events, and resolve the most common errors that occur during the Autotask sync workflow.

In this article

• System Logs page
• Overview tiles
• Filter the log list
• Log grid columns
• Common log event types
• Troubleshoot common errors

System Logs page

The System Logs page provides visibility into the integration's activity over the last 30 days. You can access it from the left navigation inside the Autotask integration area (Logs & Monitoring).

The page contains four overview tiles, a level filter dropdown with an entry count label, and a paginated grid of log entries. Each entry uses one of three severity levels: INFO, WARN, or ERROR.

Overview tiles

Four summary tiles at the top of the page provide a snapshot of integration activity over the last 30 days. Each tile displays an icon as a visual anchor.

• Total Logs (30d) — the total number of log entries recorded (combined Info, Warn, and Error).
• Errors (30d) — the number of Error-level entries. The counter renders in red when greater than zero, and in the default text color when zero.
• Warnings (30d) — the number of Warning-level entries. The counter renders in amber when greater than zero, and in the default text color when zero.
• Last Update — the relative time since the most recent log entry. Click the refresh icon to reload.

Filter the log list

A dropdown above the grid lets you filter entries by log level. An entry count label next to the dropdown shows how many rows match the current filter. Default: All.

• All — every entry regardless of level (default).
• INFO — informational events: sync started/completed, organizations synced, invoice lines posted, etc.
• WARN — non-blocking issues, for example lines skipped because of incomplete mapping.
• ERROR — failed operations that require investigation.

Log grid columns

The grid displays one log entry per row with three columns:

• Level — severity of the entry, shown as a colored badge: INFO (slate), WARN (amber), ERROR (red).
• Timestamp — date and time of the event in YYYY/MM/DD HH:MM format, displayed in a monospace font.
• Summary — a two-line cell containing a bold primary message on the first line and a lighter sub-description with operational detail on the second line.

Common log event types

The following event types are recorded by the Autotask integration:

Info events

• Customers sync started — recorded when Sync Organizations begins.
• Customers sync completed — includes a summary of created, updated, skipped, and failed records with duration.
• Invoice lines sync started — recorded when Sync Invoices to PSA begins, including the number of lines to process.
• Invoice lines sync completed — includes a summary of posted, skipped, and failed lines with duration.
• Products loaded — recorded when Load Products completes.

Warning events

• Invoice line skipped — recorded when a line can't be synced for a known, non-error reason: zero Revenue, or incomplete mapping (Mapping Status = Unmapped). The line remains available for a manual retry after you resolve the issue.
• Customer skipped — recorded when an Organization can't be synced because its Autotask Account is inactive or the mapping is incomplete.
• Rate limit warning — recorded when the integration reaches 70% of the Autotask API rate limit (7,000 of 10,000 requests per 60 minutes). The integration applies exponential backoff automatically (2s → 4s → 8s → 16s → 32s) and retries without manual intervention.

Error events

• Contract type validation error — the mapped Autotask Contract isn't a Recurring Service Contract (contract type 7). Autotask returns a 400 validation error when a Contract Service Adjustment is posted to any other contract type.
• Billing Code missing — no Material Code could be resolved for a non-recurring Charge Type (Usage Fee, Correction, User Correction, Item Fee, One Time Fee) after checking all resolution steps (per-charge-type mapping, then Default Material Code ID). The sync is blocked for that line.
• Unmapped customer — sync was attempted on a line whose PSA Organization is missing or whose Excluded from Sync flag is set to Yes.
• Connection failure — the integration can't reach Autotask or receives an authentication error. Includes field-level error messages returned by the Autotask API where available.
• 500 / 503 from Autotask API — the integration retries automatically (3 retries, 30s fixed delay). If all retries fail, the line is deferred to the next sync and an error entry is logged.

Troubleshoot common errors

Test Connection fails

Likely causes:

• Incorrect Username or Secret.
• The API user was deactivated in Autotask.
• The API user wasn't linked to the AppXite Integration Vendor, or the Custom (Internal Integration) checkbox was checked instead. For details, see How to obtain Autotask credentials.

What to do: Verify each credential against your Autotask instance. If the Integration Vendor isn't set correctly, in Autotask edit the API user, select AppXite in the Integration Vendor dropdown, uncheck Custom (Internal Integration), and save. Then re-enter the credentials in the Platform.

Connects successfully but Organizations or Contracts don't load

Likely cause: The API user's Security Level is missing permission on the Companies/Accounts or Contracts entity.

What to do: Review the required permissions in How to obtain Autotask credentials and add the missing permission on the Security Level in Autotask, then re-test the connection.

"Contract type validation error" / 400 error when posting recurring lines

The mapped Autotask Contract isn't a Recurring Service Contract. Autotask returns a 400 validation error when a Contract Service Adjustment is posted to any other contract type (Time and Materials, Fixed Price, Block Hours, etc.).

What to do: In the Platform, open Mapping → Contracts, remove the incorrect mapping, and map the line to a valid Recurring Service Contract. Alternatively, enable Auto-Create Recurring Contract on the Configuration tab to have the Platform create one automatically.

"Billing Code missing" — sync blocked for a non-recurring line

No Material Code was resolved for the Charge Type of that line. The Platform checks in this order: per-charge-type mapping in Settings → Configuration, then the Default Material Code ID. If neither is set, the sync is blocked.

What to do: In the Platform, go to Settings → Configuration → Material Code Mappings and assign a Material Code to the relevant Charge Type, or set a Default Material Code ID as a fallback. Click Save Configuration, then retry the sync.

"Unmapped customer" / line with no PSA Organization

A sync was attempted on a line whose PSA Organization column is empty, or whose Excluded from Sync flag is set to Yes.

What to do: In the Platform, go to Mapping → Organizations, complete the mapping for the affected Organization, and set Excluded from Sync to No. Then reload and retry the Invoice Line.

Line shows ERROR Sync Status after sync

What to do:

1. In the Platform, go to Logs & Monitoring and filter by ERROR.
2. Find the entry matching the affected line — the Summary sub-description contains the Autotask API error message where available.
3. Resolve the root cause (incorrect mapping, contract type, missing billing code, or permission issue).
4. Go to Mapping → Invoices and retry the line individually using the Sync Invoice Line icon on that row.

Still need help?

If an Error entry doesn't match any of the scenarios above, or keeps recurring after following the suggested steps, contact Platform Support. Include the timestamp and Summary text from the relevant log entry to help the Support team identify the root cause quickly.

Summary

The System Logs page is the primary tool for monitoring Autotask integration health and diagnosing sync issues. Check the overview tiles for a quick count of errors and warnings, use the level filter to focus on specific event types, and refer to the troubleshooting sections above when a specific error appears. For credential-related issues, see How to obtain Autotask credentials. For mapping-related issues, see Autotask integration: Mapping organizations, products and contracts and Autotask integration: Loading and syncing invoice lines.

Related content

• Autotask integration overview
• First steps with the Autotask integration
• How to obtain Autotask credentials
• Autotask integration: Mapping organizations, products and contracts
• Autotask integration: Loading and syncing invoice lines