Before Payroll reads or writes a single record, it has to prove it can reach CheckHQ, the payroll engine behind the Payroll connector. That check runs once, at the very start of the step, before any employee, contractor, or other record is touched. If that check fails for any reason, the entire sync run stops immediately, not just the step that was starting.
This family covers the ways that opening check can fail: an internal credential Arcoro did not read correctly, a Company ID on the connector that CheckHQ does not recognize, or CheckHQ telling Arcoro to slow down its requests.
Error Messages
| Message text | Direction | Occurs when | Outcome | Fix |
|---|---|---|---|---|
| Payroll Provider could not read the required configuration setting for the API Token. Try the Sync again and if this problem persists contact Arcoro support. | Both (read and write) | The internal API Token setting Payroll uses to call CheckHQ is blank when the connector authenticates. This is an internal Arcoro setting, not a field you can interact with. | Sync stopped | Escalate immediately; there is nothing for you to change. |
| Payroll Provider could not find the provided CompanyId. Please verify the connector properties and run the Sync again. If the problem persists contact Arcoro support. | Both (read and write) | After the connector authenticates, Payroll asks CheckHQ for the company and compares its id to the CompanyId (or Business Unit, if one is set) configured on the connector. They do not match. | Sync stopped | Correct the CompanyId field, and the Business Unit field if one is set, on the connector. |
| The Payroll Provider surpassed the requests threshold and did not suggest a retry interval. | Both (read and write) | CheckHQ returned a rate limit response, and one of three things happened: Payroll had already retried 5 times, or the response did not include a retry-after value, or that value was not a whole number of seconds. | Sync stopped | Re-run the sync later. Escalate if it keeps happening. |
| The Payroll Provider surpassed the requests threshold, and the proposed retry duration of [number of seconds CheckHQ asked Arcoro to wait] seconds exceeds the maximum allowed time. | Both (read and write) | CheckHQ returned a rate limit response with a retry-after value, but that value was negative or greater than 60 seconds, which is more than Payroll will wait. | Sync stopped | Re-run the sync later. Escalate if it keeps happening. |
Confirming the Error
- Open the sync execution for the run in question, from Sync History.
- Open the step for the Payroll connector.
- Check whether every entity in that step shows zero for Added, Updated, and Unchanged, with no per-entity Errors or Warnings either. That pattern, and not a count against one entity, is what this family looks like: the connection check runs before any entity starts, so nothing gets far enough to log its own Errors or Warnings.
- Look at the overall status of the sync execution rather than one entity row. The failure is recorded at the run level, not tied to a specific entity, because the entity context is closed out before the failure is finally recorded.
- Match the failure text against the fixed part of the sentence in the table above, ignoring the number inside the retry duration message.
- A non-zero Failures count on an individual entity is not what this family produces. If you see Errors or Warnings recorded against a specific entity instead of a run-level failure with nothing processed, the ticket belongs in a different article.
Resolving the Error
Missing Configuration Setting for the API Token
- There is no end user-facing setting to check. This value is read from Arcoro's own configuration, not from anything on the connector.
- Escalate to Arcoro support with the sync execution identifier, the connector, and the time of the run.
Companyid Not Recognized
- In Arcoro, open the connector for this Payroll integration.
- Confirm the CompanyId field holds the correct CheckHQ Company ID for your organization.
- If a Business Unit is selected on the connector, confirm it is the correct business unit; when set, it is used instead of CompanyId to authenticate.
- Save the connector and run the sync again.
- Confirm the fix by re-running the sync and checking that the run completes and the entities in that step now show Added, Updated, or Unchanged counts.
Requests Threshold Surpassed (Both Retry Messages)
- There is no connector setting to change. CheckHQ is asking Arcoro to slow down, or has stopped answering fast enough for Payroll's retry limit.
- Wait and re-run the sync later.
- Confirm the fix by re-running the sync and checking that the run completes and the entities in that step now show Added, Updated, or Unchanged counts.
When to Escalate
If any of the following occur, you may need to reach out to Arcoro support for additional assistance.
- The API Token message appears at all. Tier 1 has no setting to change for it.
- The CompanyId message persists after the CompanyId and Business Unit fields are confirmed correct on the connector.
- Either the requests-threshold message repeats across multiple sync runs rather than clearing on a later retry.
- The message text in the log does not match any row in the table above. It may be a passthrough message from CheckHQ's own API rather than one of these four Arcoro messages, and needs a developer to confirm.
- The outcome is anything other than the whole run stopping, since that is not how this family behaves.