Skip to main content

UKG Pro Error Messages

Error messages a subscriber may see when the UKG Pro integration transfers employees into iPaaS.com, what causes each one, and how to resolve it.

Overview

This article catalogs every error the UKG Pro integration can record in the iPaaS.com error logs, grouped by the flow that produces them. Each entry carries a stable error code, the message exactly as it appears in the log, what causes it, and how to resolve it. To look one up, find the code at the start of the logged message — for example UKGP-EXTN-1002 — and search this page for it.

Errors appear in iPaaS.com under Dashboard / Integration Monitoring / Error Logs. Codes are permanent: the wording of a message may be refined over time, but a code always refers to the same condition.

Some resolutions below refer to your Managed Integration Service Provider (MiSP) — the partner who set up and maintains your iPaaS.com subscription. Your MiSP owns your mapping collections, subscription settings, and stored credentials, so they are the right first contact for anything this article cannot resolve directly.

Some integration behaviors produce no error at all — for example, an employee filtered out by employment status is skipped silently rather than failing. Those behaviors are described in the UKG Pro Integration Known Limitations article and in each mapping collection's description, not here.

iPaaS.com categorizes errors by families. You can learn more about that categorization at Understanding iPaaS.com API Error Codes.

Supported Flows

  • Connection and Authentication

  • Add/Update UKG Pro Employee TO iPaaS.com

  • Add/Update UKG Pro Employee Address TO iPaaS.com

  • Employee Write-Back FROM iPaaS.com

Error Collection

Connection and Authentication

Connection Validation Failed

UKGP-AUTH-1001 - Unable to validate the UKG Pro connection. {reason}

  • Description: Before any transfer runs, the integration validates its UKG Pro connection by requesting the tenant's company details. This error is recorded whenever that request does not succeed. {reason} carries what UKG Pro returned, or the network error the request failed with — a rejected credential, a service account that has lost access, an incorrect tenant host, or a path that never reached UKG Pro at all. When the failure produced no reason at all, the message ends after the first sentence.

  • Resolution: Read {reason} first — it usually names the cause directly. Then work through the four connection values on the iPaaS.com Subscription Settings page in order. Confirm API Url is the tenant's UKG Pro service host in the form https://{hostname}.ultipro.com, as shown in UKG Pro under System Configuration > Security > Web Services. Confirm API Key matches the customer API key on that same page. Confirm API Username and API Password belong to an active web service account — UKG Pro displays a service account password only once, so a lost password must be regenerated in UKG Pro and re-entered in iPaaS.com. Then confirm in UKG Pro under System Configuration > Security > Service Account Administration that the account is active and retains View access to the Employee Person Details, Employee Employment Details, Compensation Details, Platform Configuration Fields, and Company Details web services. If all four values are correct and the service account is healthy, ask your MiSP to confirm the subscription's stored credentials match what you verified and that UKG Pro is reachable from the iPaaS.com platform.

Add/Update UKG Pro Employee TO iPaaS.com

UKG Pro Request Limit Reached

UKGP-EXTN-1001 - Received a Too Many Requests response from UKG Pro. There is no indication when more requests might be accepted.

  • Description: UKG Pro rejected a request because too many calls were made in a short period. UKG Pro returns no indication of when capacity will return, so the integration cannot schedule a precise retry and stops the affected transfer instead.

  • Resolution: No action is required for a one-off occurrence — the affected employees are captured on the next scheduled run. If the message recurs, pace the integration more conservatively on the Subscription Settings page: lower API Throttle Limit or raise API Throttle Seconds, and lower Concurrent Connections if several transfers run at once. UKG Pro does not publish rate-limit figures for the endpoints this integration calls, so workable values are best established by observation. If throttling continues at conservative settings, raise the pattern with UKG.

UKG Pro Request Failed

UKGP-EXTN-1002 - Error calling UKG Pro CallWrapper.{action}{errMsg} (Http Code: {statusName} ({statusNumber}))

  • Description: A request for person, employment, compensation, or configuration-field data failed. This is the integration's general-purpose reporting point for any UKG Pro response it cannot use, so the detail that matters is inside the message rather than in the code. {action} names the call that failed, {errMsg} carries the reason UKG Pro returned, and the HTTP status appears as both its name and its number — for example (Http Code: NotFound (404)) — so the log can be searched either way. A status of 0 (0) means the request never reached UKG Pro at all, which points to a network, DNS, or TLS failure rather than anything UKG Pro rejected.

  • Resolution: Read the HTTP status first. Unauthorized (401) or Forbidden (403) means the service account no longer authenticates or has lost access to one of the web services listed under Connection Validation Failed above — re-check it in UKG Pro under System Configuration > Security > Service Account Administration. NotFound (404) usually means the requested employee no longer exists in the tenant, which needs no action. ServiceUnavailable (503), InternalServerError (500), or 0 (0) are transient: the employee is re-captured on the next scheduled run, or immediately by running a Manual Sync. If failures continue past a short window with correct credentials, send the full message — code, action, and UKG Pro's reason — to your MiSP, and if they cannot resolve it, to iPaaS.com Support at support@ipaas.com.

Add/Update UKG Pro Employee Address TO iPaaS.com

No Errors Specific to This Flow

  • Description: The Employee Address collection runs as part of its parent employee transfer and makes no separate calls to UKG Pro, so it produces no error messages of its own. When an address fails to arrive, the cause is a failure in the parent employee transfer.

  • Resolution: Resolve the parent employee error listed under Add/Update UKG Pro Employee TO iPaaS.com above. Once the employee transfers successfully, its address is captured with it.

Employee Write-Back FROM iPaaS.com

The UKG Pro integration reads employee data out of UKG Pro; it does not write employee data back. The three errors below are recorded when a mapping collection is configured to send employees to UKG Pro, and all three are resolved the same way.

Employee Creation Not Supported

UKGP-BIZL-1001 - UKG Pro employees cannot be created from iPaaS.com. This integration reads employee data from UKG Pro only.

  • Description: A transfer attempted to create an employee in UKG Pro. The integration supports no write operations against UKG Pro, so the transfer stops rather than sending the record.

  • Resolution: Ask your MiSP to review the mapping collection that produced this error and set its direction to To iPaaS, or remove the collection if it was created in error. Employee records must be created in UKG Pro directly; iPaaS.com captures them on the next transfer.

Employee Update Not Supported

UKGP-BIZL-1002 - UKG Pro employees cannot be updated from iPaaS.com. This integration reads employee data from UKG Pro only.

  • Description: A transfer attempted to update an existing employee in UKG Pro. The integration supports no write operations against UKG Pro, so the transfer stops rather than sending the changes.

  • Resolution: Ask your MiSP to review the mapping collection that produced this error and set its direction to To iPaaS, or remove the collection if it was created in error. Employee changes must be made in UKG Pro directly; iPaaS.com captures them on the next transfer.

Employee Deletion Not Supported

UKGP-BIZL-1003 - UKG Pro employees cannot be deleted from iPaaS.com. This integration reads employee data from UKG Pro only.

  • Description: A transfer attempted to delete an employee in UKG Pro. The integration supports no write operations against UKG Pro, so the transfer stops rather than sending the request.

  • Resolution: Ask your MiSP to review the mapping collection that produced this error and set its direction to To iPaaS, or remove the collection if it was created in error. Employee records must be removed in UKG Pro directly.

Related Documents

Related Articles
Did this answer your question?