Troubleshooting

Symptom → likely cause → fix for the most common issues across sign-in, the candidate experience, scoring, resumes, email, billing, integrations, and the Partner API.

If a fix here doesn't resolve your issue, contact support@cocolevio.com with the specifics (account email, job/candidate IDs, timestamps, and any error text).

Can't sign in / "invalid credentials".

Cause: wrong password, or the account uses SSO.
Fix: use the exact email on the account; if your company set up Google/Microsoft SSO, use the SSO button instead of a password. Reset your password from the sign-in page if needed.

Account is locked.

Cause: login anomaly detection flagged unusual activity (new location/device, repeated failures).
Fix: wait and retry from your usual device/network, or contact support@cocolevio.com to unlock.

Two-factor code rejected.

Cause: device clock drift, or an expired TOTP code.
Fix: ensure your phone's time is set to automatic, then enter a fresh code. If you lost your authenticator, contact support to reset 2FA.

Candidate camera / microphone / screen issues

Camera or microphone not working at the start of the assessment.

Cause: browser permission denied, or another app is using the device.
Fix: grant camera and mic permission when prompted, close other apps using the camera (video-call tools), and reload the assessment link. Use a modern desktop browser (Chrome recommended).

Screen recording won't start.

Cause: screen-share permission not granted, or an unsupported browser.
Fix: accept the screen-share prompt and select the correct screen. Switch to an up-to-date desktop browser if the option doesn't appear.

Copy/paste doesn't work during the test.

Cause: expected behaviour — copy/paste is intentionally blocked during assessments.
Fix: none needed; candidates must type or speak their answers directly.

Report shows camera/mic as disabled (isVideoEnabled: false).

Cause: the candidate declined permission or had no working device.
Fix: this is a recorded integrity signal, not an error. A recruiter reviews it alongside the answers; it does not auto-reject. See Anti-cheat and proctoring.

Assessment not scoring / needs re-assessment

Report status stuck at "In Progress" or "Not Started".

Cause: the candidate hasn't finished, or the assessment wasn't submitted.
Fix: confirm the candidate completed and submitted all questions. Poll GET /apikey/get_candidate_report/{p_candidate_id} until assessment_status is Completed. assessment_result populates only after completion.

assessment_result is empty even though status is "Completed".

Cause: scoring may still be finalising, or answers were empty.
Fix: re-fetch the report after a short delay. If answers exist but no scores appear, contact support with the candidate ID.

Scores look wrong for a spoken answer.

Cause: transcription mis-heard technical terms.
Fix: read the transcript in the report to confirm what was captured. Because AI scores are decision support, review the transcript/recording and adjust your judgement — the recruiter sets the verdict. See How AI scoring works.

Want to re-assess a candidate.

Cause: you changed the role, skills, or question set.
Fix: update the assessment (dashboard or POST /apikey/update_assessment) and issue a new candidate link. Existing completed attempts keep their original results.

Resume not parsing

Contact extraction returns null name/email/phone.

Cause: the PDF is a scanned image (no selectable text), or an unusual layout.
Fix: use a text-based PDF (not a photo/scan). If the layout is atypical, extract fields manually or try AI parsing (p-resume-parsing).

"Could not read PDF" / 422 error.

Cause: the file is empty, not a PDF, or corrupted.
Fix: re-export as a valid PDF and resend as multipart/form-data with the file field.

AI resume parsing fails or returns empty data.

Cause: the parse failed, or your resume-token quota is exhausted (returns an error).
Fix: check your token balance; top up if needed. Ensure file, job_requirement, and skill_set are all sent. Retry with a cleaner PDF.

Email not received (invites / OTP / reports)

Candidate didn't get the assessment invite.

Cause: email in spam, wrong address, or you shared the link out-of-band.
Fix: the API returns the assessment_link directly from process_candidate — you can send it yourself via any channel. Verify the candidate's email and ask them to check spam/junk.

One-time passcode (OTP) email not arriving.

Cause: delivery delay or spam filtering (email is sent via AWS SES).
Fix: wait a minute, check spam, and request a new code. Whitelist the Coco HR sender domain if your org filters aggressively.

Report notification not received.

Cause: notification preference or spam filtering.
Fix: fetch the report directly from the dashboard or GET /apikey/get_candidate_report/{p_candidate_id} rather than relying on the email.

Payment / past-due

Account shows "past due" or features are limited.

Cause: a Stripe payment failed (expired card, insufficient funds).
Fix: update your payment method in the dashboard billing section; Stripe will retry. Contact support if access isn't restored after payment succeeds.

Metered API calls return an error about tokens.

Cause: assessment or resume token quota exhausted.
Fix: top up or wait for the quota to reset. Remember p-parse-resume-contact uses no tokens if you only need contact details.

Greenhouse connection

Greenhouse integration won't connect or stops syncing.

Cause: invalid or expired Greenhouse credentials, or revoked access.
Fix: reconnect the integration from your dashboard settings with valid credentials/permissions. If it still fails, contact support@cocolevio.com.

Partner API errors

401 Unauthorized / "Invalid API key".

Cause: missing header, wrong format, or a rotated (replaced) key.
Fix: send the header exactly as Authorization: ApiKey <your-api-key> (note the space and the ApiKey prefix). If you recently regenerated the key, update your integration — the old key stops working immediately. Retrieve the current key via the dashboard or GET /apikey/fetch-api-key.

400 on prepare_assessment — "assessment already exists".

Cause: an assessment already exists for that job_id.
Fix: use POST /apikey/update_assessment with the same job_id instead.

400 on process_candidate — "applicant already exists".

Cause: the same email is already registered for that p_job_id.
Fix: reuse the existing candidate/link, or register with a different email.

404 on get_candidate_report.

Cause: the p_candidate_id was never registered, or doesn't match what you sent to process_candidate.
Fix: use the exact same integer p_candidate_id you passed to process_candidate.

409 on delete_assessment.

Cause: a candidate has already submitted this assessment.
Fix: deletion is blocked to preserve the record; use update_assessment instead.

422 on any request.

Cause: malformed body or upload — for example non-integer IDs, or a missing/non-PDF file.
Fix: ensure job_id, p_job_id, and p_candidate_id are integers, and that multipart uploads include the file field. See the Partner API reference.

Need more help? Email support@cocolevio.com or see the FAQ.