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.
Related: Frequently asked questions · Status glossary