Payroll batch - common errors


  1. An error has occurred

    1. Cause

      1. One of the workers have not been finalized (incomplete), or has been terminated in KeyPay

    2. Fix

      1. Ask the client to resolve the issue in KeyPay.

      2. If the client confirms there is no issue with the workers, but is still unable to export, contact the payroll champion so they can ask KeyPay about this.

      3. V3 instances will tell you which workers are incomplete

        1. Keypay set up is incomplete for <<worker name>>

  2. PayCategoryId does not match an id for any PayCategory

    1. Possible causes:

      1. Confirm with the client if the paycategory exists in KeyPay

      2. Confirm with the client if the timesheet’s pay category is not a System pay category in KeyPay (you cannot export timesheets using system pay categories)

        1. In KeyPay, it will show system beside the name if it is a system pay category


    2. Fix

      1. If the pay category does not exist or is a system pay category, as the client to follow the steps below to resolve the issue

        1. create a new pay category in KeyPay,

        2. sync it to Expedo,

        3. update the engagement and assignment with the new pay category

        4. re-verify the timesheet

      2. permanent fix is to exclude system pay categories from being synced to Expedo.

        1. Ticket for reference:

  3. StartTime for <<worker name>> cannot be before employee start date (<<start date>>)

    1. Cause

      1. The timesheet’s period is earlier than the employee start date in KeyPay

    2. Fix

      1. Ask the client to update the employee start date in KeyPay and re-export the payroll batch

  4. Error 504: Gateway timeout

    1. Cause

      1. KeyPay is down

    2. Fix

      1. Ask client to wait for a few minutes before re-exporting the payroll batch

  5. Key does not match an id for any employee

    1. Cause

      1. The Expedo worker’s KeyPay ID is incorrect

    2. Fix

      1. Update the worker profile with the correct KeyPay ID

  6. Payroll batch stuck at exporting


      1. Check if the payroll batch has a Pay run # in the list


      2. If there is a pay run #, this means that the pay run has been created in KeyPay. Please confirm with the client if the Pay run is still in KeyPay.

    2. Cause

      1. If the client cannot find the pay run in KeyPay, it is possible that they have deleted it themselves, or it was automatically deleted by KeyPay.

      2. KeyPay automatically deletes pay runs if there are invalid data. This is usually caused by pay run inclusions/super adjustments that don’t have values in KeyPay.

        1. Note - this is KeyPay’s response related to this issue:

    3. Fix

      1. Please ask the client to check if there are any workers with super adjustments or pay inclusions that don’t have amounts or types.

      2. Once the client has cleaned up the data in KeyPay. The Dev team will revert the payroll batch's status to pending in order for the user to re-export the batch.

  7. Unauthorized

    1. Cause

      1. The API Key of the Employer of Record is already expired or not authorized to do any transactions

    2. Fix

      1. Ask the client to generate a new API Key (taken from the KeyPay site with a similar Business ID in the Integration Settings in Expedo) and update it.