Help

Troubleshooting

Common blockers in onboarding, payroll and integrations, with the cause and what to do. If your problem isn't on the list, write to Onboardly support.

Onboarding and the candidate wizard

Problem	Cause and solution
KYC rejected	Most often poor photo quality of the document or selfie. Repeat verification in better light, without glare, with the whole document in frame. If it still fails, ask the employer to reset KYC (done by Onboardly support).
Onboarding link expired	The link has limited validity, once it lapses it leads to an “expired” page. The employer sends a new link from the panel (the resend action on the onboarding).
SMS code doesn't arrive	After sending, a 60 s interval applies before retrying. Check that the phone number in the offer is correct; after waiting, use “resend”.
Own signature wasn't saved	The signature requires confirmation with an SMS code. Make sure the code was entered and the browser is up to date. After a network error, retry, the document won't be signed twice.
Wizard won't move forward	It's blocked by gaps: pending legalization or missing industry documents. Complete the missing step, the readiness gate will unlock the signature.

Documents and legalization

Problem	Cause and solution
Worker can't upload a document	The “Complete” link is valid for 7 days and accepts files up to 10 MB (PDF/image). Once it expires, send the document request again from the panel.
Legalization is stuck	If the case is handled by an external entity, check the Partner portal, the case waits until the partner uploads the documents and closes it. Only then can you generate the contract.

Payroll and export

Problem	Cause and solution
ZUS/KEDU export blocked	The completeness gate requires: full name, PESEL (or a foreign worker's document), date of birth, home address, start date, payer NIP, a valid insurance-title code and NFZ code. Complete the items on the blockers list and retry the export.
Import didn't match a worker	Import matches by PESEL (fallback: first name + last name + date of birth) and runs in conservative mode, it does not create new workers. Unmatched ones you set up via onboarding or import of existing workers.
Insurance-title code “low confidence”	For some contracts the code has low confidence, confirm it before filing with ZUS. See HR export.

API and integrations

Problem	Cause and solution
401 / 403 error from the API	401, missing or wrong key; 403, the key lacks the required scope. Check the header and the key's scopes. See API authentication.
429 error (limit)	Request limit exceeded. Wait until the time in the `X-RateLimit-Reset` header and retry (exponential backoff). See Errors, limits and pagination.
Webhook doesn't arrive	Check the URL and secret in settings and the HMAC signature verification. Failed deliveries are retried; an event can be resent. See Webhooks.

Didn't find a solution? Write to Onboardly support, some operations (e.g. KYC reset) are performed by the support team.