https://api.certo.bio/v1openapi.json

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

CodeWhat it meansHow to fix it
apply.unknownNo button has that idCopy the id again from the Integrations page, the position or the session's answer
apply.pausedApply with certo is switched off for your company, certo paused it, or the company profile is no longer completeSwitch it on; complete the profile; read certo's note on the Integrations page
apply.position_closedThe position is closed, or no longer accepts applicationsReopen it and switch Accept applications with certo on, or take the button down
apply.position_invalidAn apply session names a position that is not yoursSend one of your positions' ids
apply.origin_not_allowedThe page that opened the popup is not one of your live sites, or the popup was opened without a pageAdd 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_allowedThe return address is not registered, character for characterRegister it exactly as you send it
apply.test_origin_members_onlyA localhost page, and the person applying is not a member of your companyTest with your own account
apply.own_organisationA member of your company applied from a live siteTest on localhost, or with someone who is not a member
apply.no_passportThe person has no passport yetThe popup offers to make one; nothing for you to do
apply.payment_requiredYour company asks candidates whose verification is not paid to pay first, and this one has notThe 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_coveredYour company covers new candidates' verification, has no verifications left, and chose to refuse applications thenAdd verifications, or choose what happens with none left
apply.funding_invalidA choice of who pays that certo does not knowSend free, candidate_pays or company_pays, and free, candidate_pays or refuse
apply.not_set_upWho pays was set before Apply with certo wasSwitch Apply with certo on first
apply.field_invalidThe job's words or the state are too long or not plain textKeep 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_usedAn Apply already spent this apply sessionMake a new session on every click
apply.session_expiredThe apply session is over an hour old and was never usedMake sessions on the click, not when the page loads
apply.general_terms_missingAn ao_ button, or a session falling back to the general terms, and none are savedSave the general application; or give the terms in the session
apply.rate_limitedToo many in a short time: 30 applications a day per passport, popups opened from one address, 5000 apply sessions an hour per companyWait; make sessions on the click only
apply.unavailablecerto cannot sign applications just nowTry again in a minute; the candidate's Apply is safe to repeat
apply.not_openThe application closed between Apply and its deliveryThe candidate withdrew it; nothing to deliver
apply.platform_onlyA call that only certo's own pages may makeUse the button, the console or the API

Setting it up, and the API

CodeWhat it meansHow to fix it
apply.not_employerThe organisation is not an employerApply with certo is for employers
apply.delivery_requiredNeither delivery is chosenDeliver to the page, to your server, or both
apply.terms_invalidThe terms do not fit: employer scopes only, a reason with the date of birth, requirements as a position takes themFix the field the message names
apply.fields_invalidSettings or a session with a field Apply with certo does not takeSend only the documented fields
apply.origin_invalidA site that is not https:// and a host name, with nothing after itFor example https://jobs.hireline.example; for testing http://localhost:3000
apply.redirect_invalidA return address that is not https on a host name, or has a fragmentDrop the fragment; use https
apply.origin_limit50 sites and return addresses alreadyRemove the ones you no longer use
apply.origin_not_foundRemoving a site that is not thereReload the list
apply.not_allowedThe key may not make apply sessionsUse a key with hiring:invite
apply.not_set_upcerto was asked to pause an integration that was never set upNothing 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.