External Payrolls Validations

1. Payroll Creation Errors

Validation Errors

• Empty Payroll Error
  • When: Approving an external payroll
  • Error: EmptyPayrollError
  • Message: "Payrolls must have at least one item or contractor payment to be previewed or approved"
  • Prevention: Ensure at least one payroll item or contractor payment is included
• Company Mismatch Error
  • When: Creating/updating payroll items or contractor payments
  • Error: ValidationError
  • Message: "Employee/Contractor company does not match payroll company"
  • Prevention: Verify all employees and contractors belong to the same company as the payroll
• Invalid Date Range Error
  • When: Creating/updating payroll
  • Error: ValidationError
  • Message: "Period start must be before period end"
  • Prevention: Ensure period_start date is before period_end date
• Managed Payroll Year Conflict
  • When: Creating external payroll
  • Error: ValidationError
  • Message: "Cannot submit external payrolls through the API for companies that have run managed payrolls in {year}"
  • Prevention: Load all external payrolls before activating company - if an additional payroll is required after managed payrolls are run on Check, contact Check support.

2. Payroll Item Errors

Earning Validation

• Invalid Earning Type/Code Combination
  • When: Creating/updating payroll items
  • Error: ValidationError
  • Message: "Cannot provide type and earning_code" or "Must provide type or earning_code"
  • Prevention: Provide either an earning type or an earning code, not both
• Invalid Hours for Earning Type
  • When: Creating/updating payroll items
  • Error: ValidationError
  • Messages:
    • "Non-zero hours must be provided for {type} earnings" (for hourly types)
    • "Hours must not be provided for {type} earnings" (for non-hourly types)
    • "Hours cannot be greater than total hours in a quarter"
  • Prevention:
    • Provide hours for hourly earnings
    • Don't provide hours for non-hourly earnings
    • Ensure hours don't exceed 2190 (quarterly maximum)
    • See our Types of Earnings documentation for earning type categorization

Duplicate Items

• Duplicate Payroll Item Error
  • When: Creating/updating payroll items
  • Error: DuplicatePayrollItemError
  • Prevention: Employees can only have one item per payroll. Ensure unique combinations of employee, period, and earnings
• Duplicate Contractor Payment Error
  • When: Creating/updating contractor payments
  • Error: DuplicateContractorPaymentError
  • Prevention: Contractors can only have one item per payroll. Ensure unique combinations of contractor, period, and payment details

3. Tax and Benefit Errors

Tax Validation

• Tax Amount Validation
  • When: Creating/updating payroll items with taxes
  • Error: ValidationError
  • Messages:
    • "Non-zero amount must be provided"
    • "If taxable_wages is provided, gross_taxable_wages must also be provided"
    • "taxable_wages must be less than or equal to gross_taxable_wages if amount is positive"
    • Prevention: Ensure proper tax amounts and corresponding taxable wages
• Negative Tax QTD Error
  • When: Approving payroll
  • Error: ValidationError
  • Message: "Cannot approve payroll since one or more taxes have negative amounts causing negative quarter-to-date amounts"
  • Prevention: Ensure tax amounts don't create negative quarter-to-date balances
• Taxable Wages Exceeds Gross Pay
  • When: Approving payroll
  • Error: ValidationError
  • Message: "Cannot approve payroll since one or more taxes have a gross_taxable_wages that is greater than the total gross pay"
  • Prevention: Ensure taxable wages don't exceed total gross pay

Benefit Validation

• Benefit Contribution Validation
  • When: Creating/updating payroll items with benefits
  • Error: ValidationError
  • Message: "Employee contribution amount or company contribution amount must be defined"
  • Prevention: Provide at least one contribution amount for benefits
• Negative Benefit Contribution Error
  • When: Approving payroll
  • Error: ValidationError
  • Message: "Cannot have negative employee or company contribution amounts unless all earnings are positive"
  • Prevention: Ensure benefit contributions are positive unless all earnings are positive

4. Payroll Status Errors

• Payroll Approved Error
  • When: Modifying an approved payroll
  • Error: PayrollApprovedError
  • Message: "Payroll must be approved"
  • Prevention: Only modify payrolls in draft status
• Payroll Not Draft Status Error
  • When: Updating a non-draft payroll
  • Error: PayrollNotDraftStatusError
  • Prevention: Only update payrolls in draft status
• Payroll Blocked Error
  • When: Any operation on a blocked payroll
  • Error: PayrollBlockedError
  • Message: "Payroll for {company_id} is currently on hold"
  • Prevention: Contact Check support if payroll is blocked

5. Net Pay Validation

• Negative Net Pay Error
  • When: Creating/updating payroll items
  • Error: ValidationError
  • Message: "Cannot have negative net pay: {amount} for employee {id} on {date}"
  • Prevention: Ensure earnings and deductions result in positive net pay

Best Practices for Error Prevention

1. Data Validation
   • Validate all dates before submission
   • Ensure company consistency across all entities
   • Verify tax and benefit calculations
   • Confirm earning fields are correct for the earning type being created (e.g., hours, amount, piece)
2. Status Management
   • Check payroll status before operations
   • Handle draft vs. approved states appropriately
3. Amount Validation
   • Validate all monetary amounts
   • Ensure proper relationships between gross pay, taxable wages, and deductions
   • Check for negative amounts where not allowed
4. Error Handling
   • Implement proper error handling in your integration
   • Handle both field-specific and general validation errors

This guide should help you prevent common errors and handle them appropriately when they occur. Always test your integration thoroughly and validate data before submission to minimize errors in production.