Apply with certo: errors and troubleshooting
Every apply code with what it means and how to fix it, then the problems integrators meet most: a blocked popup, a site waiting for certo, a spent session.
6 minute read
A refusal in the popup shows the candidate a sentence and its code; most come before anyone signs in. The API answers the same codes in its usual error shape (Errors, limits and retries).
In the popup
| Code | What it means | How to fix it |
|---|---|---|
apply.unknown | No button has that id | Copy the id again from the Integrations page, the position or the session's answer |
apply.paused | Apply with certo is switched off for your company, certo paused it, or the company profile is no longer complete | Switch it on; complete the profile; read certo's note on the Integrations page |
apply.position_closed | The position is closed, or no longer accepts applications | Reopen it and switch Accept applications with certo on, or take the button down |
apply.position_invalid | An apply session names a position that is not yours | Send one of your positions' ids |
apply.origin_not_allowed | The page that opened the popup is not one of your live sites, or the popup was opened without a page | Add the site under Where it runs; wait for certo's review if it is outside your checked domains; open the popup from your button |
apply.redirect_not_allowed | The return address is not registered, character for character | Register it exactly as you send it |
apply.test_origin_members_only | A localhost page, and the person applying is not a member of your company | Test with your own account |
apply.own_organisation | A member of your company applied from a live site | Test on localhost, or with someone who is not a member |
apply.no_passport | The person has no passport yet | The popup offers to make one; nothing for you to do |
apply.payment_required | Your company asks candidates whose verification is not paid to pay first, and this one has not | The popup takes them to pay and back; nothing for you to do, or choose another option under When a candidate's verification is not paid |
apply.not_covered | Your company covers new candidates' verification, has no verifications left, and chose to refuse applications then | Add verifications, or choose what happens with none left |
apply.funding_invalid | A choice of who pays that certo does not know | Send free, candidate_pays or company_pays, and free, candidate_pays or refuse |
apply.not_set_up | Who pays was set before Apply with certo was | Switch Apply with certo on first |
apply.field_invalid | The job's words or the state are too long or not plain text | Keep job_ref to 200 characters, the title and the hiring company to 120, the URL to 2048 and http or https, the state to 200 printable characters without spaces, quotes or angle brackets |
apply.session_used | An Apply already spent this apply session | Make a new session on every click |
apply.session_expired | The apply session is over an hour old and was never used | Make sessions on the click, not when the page loads |
apply.general_terms_missing | An ao_ button, or a session falling back to the general terms, and none are saved | Save the general application; or give the terms in the session |
apply.rate_limited | Too many in a short time: 30 applications a day per passport, popups opened from one address, 5000 apply sessions an hour per company | Wait; make sessions on the click only |
apply.unavailable | certo cannot sign applications just now | Try again in a minute; the candidate's Apply is safe to repeat |
apply.not_open | The application closed between Apply and its delivery | The candidate withdrew it; nothing to deliver |
apply.platform_only | A call that only certo's own pages may make | Use the button, the console or the API |
Setting it up, and the API
| Code | What it means | How to fix it |
|---|---|---|
apply.not_employer | The organisation is not an employer | Apply with certo is for employers |
apply.delivery_required | Neither delivery is chosen | Deliver to the page, to your server, or both |
apply.terms_invalid | The terms do not fit: employer scopes only, a reason with the date of birth, requirements as a position takes them | Fix the field the message names |
apply.fields_invalid | Settings or a session with a field Apply with certo does not take | Send only the documented fields |
apply.origin_invalid | A site that is not https:// and a host name, with nothing after it | For example https://jobs.hireline.example; for testing http://localhost:3000 |
apply.redirect_invalid | A return address that is not https on a host name, or has a fragment | Drop the fragment; use https |
apply.origin_limit | 50 sites and return addresses already | Remove the ones you no longer use |
apply.origin_not_found | Removing a site that is not there | Reload the list |
apply.not_allowed | The key may not make apply sessions | Use a key with hiring:invite |
apply.not_set_up | certo was asked to pause an integration that was never set up | Nothing for you to do |
Other codes come from the rules every request shares: organisation.profile_incomplete (complete the company profile), custom_data.invalid (an object, at most 4096 bytes), api.scope_missing and the rest of the API's codes.
The popup is blocked
Browsers allow a popup only in direct answer to a click. Call CertoApply.open inside the click handler, never after an await, a timer or a network call. With an apply session, pass session: () => ... and let v1.js make the call: it opens the popup at once on https://certo.bio/apply/wait and moves it to the session when your server answers. In an in-app browser that blocks every popup, use redirect mode.
The site is waiting for certo
A site outside your company's checked domains waits for certo's review, and the button answers apply.origin_not_allowed there until it is allowed. The Integrations page shows its status and, once decided, certo's note. To be live at once, run the button on one of your checked domains, or test on localhost.
A spent session on a double click
Two clicks on one button, with one session made per page, open two popups on the same as_ id: the second Apply answers apply.session_used. Make the session inside session: () => ..., which runs once per click, and disable your button until onApplied, onSubmitted or onCancel is called.
The token is refused
Read the reason your verifier answers (client side): nonce (the state you kept for this visitor is not the one on the button: make it per visitor and keep it in their session), aud (compare with the id the button opened with, or the session's as_ id), exp (verify as the token arrives; it lives ten minutes), kid (fetch the key set again), replay (the same token twice; keep the first result).
Still stuck
Write to support@certo.bio with the code and the request_id from the error, never the token or your API key.