Errors
Every error response is a problem details object (RFC 9457) with the media type application/problem+json. It always has type, title and code; status on all but a gateway_error; usually detail, a message safe to show a user; errors for a validation failure; and correlationId for an unexpected one.
invalid_json400The request body is not valid JSON.
Send a JSON body with Content-Type: application/json.
Permalinkunexpected_body400The operation takes no request body, but one was sent.
Send the request without a body.
Permalinkunexpected_query400The request has query parameters the operation does not define.
Remove the parameters listed in detail, or check their spelling.
Permalinkinvalid_path400The request path has an invalid percent-encoding.
Percent-encode each path segment, such as an externalJobId, exactly once.
Permalinkinvalid_cursor400The cursor was changed, has expired, or belongs to a list with different filters.
Start again from the first page, without a cursor.
Permalinkinvalid_idempotency_key400The Idempotency-Key header is empty, too long or not visible ASCII.
Send 1 to 255 visible ASCII characters, such as a UUID.
Permalinkcompany_id_required400A platform key sent a request without the Alfa-Company-Id header.
Name the client company the request is for in Alfa-Company-Id, using its Company ID (org_…).
Permalinkaccess_denied403The API key does not grant access to this path.
Check that the path starts /v1/integration.
Permalinkplatform_key_required403A company key called an operation only a platform key can call.
Use your platform key for /v1/integration/platform operations.
Permalinknot_a_sub_client403The company in Alfa-Company-Id is not a client your platform created.
Create the client with POST /v1/integration/platform/clients and use its companyId.
Permalinkinsufficient_scope403The API key does not have the scope this operation needs.
Generate a key with the scope the reference lists for the operation. Scopes are fixed when a key is created.
Permalinkcompany_not_connected403The API key may not act for this company: a company key named another company, or the company has not authorized your platform, or has revoked it.
Check the Company ID. For a platform key, ask the company's admin to authorize your platform in Settings › Developers.
Permalinkapi_not_enabled403The Alfa API is not switched on for this company.
Contact Alfa to switch it on.
Permalinkaccount_locked403The company's Alfa account is locked, so the API refuses every request for it.
Ask the company to contact Alfa.
Permalinksourcing_disabled403Sourcing is switched off for this company.
Ask the company to contact Alfa about sourcing on its plan.
Permalinkpayment_required402The company's Alfa account is paused or canceled, so sourcing can't start.
Ask the company to contact its Alfa account manager, then retry.
Permalinkroute_not_found404No operation matches the method and path.
Check the path against the reference.
Permalinkjob_not_found404No linked Alfa job has this id, it belongs to another company, or, when updating, publishing or closing a job, the person who created the API key cannot see it in Alfa.
Check the jobId, and that the job is linked to an ATS job.
Permalinkcandidate_not_found404No candidate has this id on a job linked to an ATS job.
Check the candidateId, including its app_ or src_ prefix.
Permalinkresume_not_available404The candidate has no resume, as with most sourced candidates.
Treat the resume as missing; resumeUrl is null for these candidates.
Permalinkinterview_not_available404The candidate has not completed an AI Interview, or its recording is not ready yet.
Wait for the webhook that carries the interview: candidate.screened on a job that interviews applicants, or candidate.interview_completed on a job that screens the resume first.
Permalinkwebhook_endpoint_not_found404No webhook endpoint is set for this key and company.
Set one with PUT /v1/integration/webhook-endpoint.
Permalinkcontact_check_endpoint_not_found404No contact check endpoint is set for this key and company.
Set one with PUT /v1/integration/contact-check-endpoint.
Permalinkdelivery_not_found404No webhook delivery has this id for this key and company.
Check the deliveryId against the delivery log.
Permalinkmethod_not_allowed405The path exists, but not for this HTTP method.
Use one of the methods the reference lists for the path.
Permalinkats_integration_conflict409The company already uses another ATS integration in Alfa.
Ask the company to disconnect the other integration first, or contact Alfa.
Permalinkjob_not_accepting_applications409The linked Alfa job is not live, or has reached its applicant limit.
Send the applicant once the job is live again, or ask the recruiter to raise the limit.
Permalinkapplication_in_progress409Another request with the same externalApplicationId is still being processed.
Wait a moment, then retry with the same externalApplicationId.
Permalinkinterview_job_in_progress409Another request is creating the interview job for this externalJobId.
Wait a moment, then send the same request again.
Permalinkjob_not_live409The linked Alfa job is not live, so sourcing cannot start.
Publish the job with POST /v1/integration/jobs/{jobId}/publish, or create it with publish: true, then start sourcing.
Permalinkjob_not_draft409The linked Alfa job is no longer a draft. A closed or archived job cannot be published, and a published job cannot be changed because its advert has already gone out.
Close the job with POST /v1/integration/jobs/{jobId}/close if it is still live, then create a new job for the ATS job with POST /v1/integration/jobs.
Permalinkpublish_in_alfa409The company uses job slots, which Alfa assigns when a recruiter publishes the job, or the draft was created in Alfa rather than through the API, so the job stays a draft.
Ask a recruiter to publish the draft in Alfa, then start sourcing.
Permalinkjob_quota_exceeded402The company has no job postings left, so the job stays a draft.
Close a job you no longer need, or contact Alfa to add job postings, then publish the draft.
Permalinkadvert_not_ready409Alfa is still writing the job advert, so the job cannot be published yet.
Publish the draft again in a minute.
Permalinkinvalid_job_advert422The job description is blank or reads as internal instructions rather than an advert.
Send a candidate-facing description, then publish the draft.
Permalinkinsufficient_sourcing_credits409The company doesn't have enough sourcing credits left for the campaign.
Ask for fewer credits, or ask the company to add sourcing credits to its plan.
Permalinkrequest_id_reused409The requestId already started a sourcing campaign with different credits.
Send a new requestId for a new campaign.
Permalinksourcing_not_started409Alfa could not start sourcing on this job, for example a demo job.
Check the job in Alfa, or contact Alfa.
Permalinkpayload_too_large413The request body is larger than the API accepts.
Send a smaller body. A resume may be at most 4 MB once decoded.
Permalinkidempotency_in_progress409A request with the same Idempotency-Key is still running.
Wait a moment, then retry with the same key to get its result.
Permalinkvalidation_failed422The request is well formed, but some values are invalid.
Each entry in errors names the field (as a JSON Pointer) and the rule it broke.
Permalinkidempotency_key_reused422The Idempotency-Key was already used on this operation for a request with a different path or body.
Use a new key for each distinct request.
Permalinkinvalid_webhook_url422The webhook or contact check URL contains a user name or password, its host does not resolve, or it resolves to a private, loopback or link-local address. A URL that is not HTTPS is 422 validation_failed.
Use an HTTPS URL without credentials that is reachable from the public internet.
Permalinkats_job_not_linked422No Alfa job is linked to this ATS job yet.
Ask a recruiter to link an Alfa job to the ATS job in the Alfa job form, then send the applicant again.
Permalinkinvalid_country422Alfa does not recognize the country of the job.
Send the country by its English name or ISO code, such as United Kingdom or GB.
Permalinkunsupported_country422Alfa does not recognize the country.
Send the country by its English name, such as United Kingdom.
Permalinkresume_required422The linked Alfa job screens resumes, and the request has none.
Send the resume. Only a job that interviews applicants takes them without one.
Permalinkunsupported_resume_type422The resume is not a PDF, Word document or plain text file.
Send application/pdf, application/msword, the Word .docx type or text/plain.
Permalinkresume_too_large422The decoded resume is larger than 4 MB.
Send a smaller file.
Permalinkinvalid_resume422The resume is empty, is not valid base64, does not match its contentType, or cannot be read.
Send the whole, readable file, base64 encoded, with its real content type. Retry with the same externalApplicationId.
Permalinkscreening_questions_incomplete422A mandatory screening question of the job has no answer.
Read the job's screeningQuestions and send an answer to each mandatory one in screeningAnswers.
Permalinkunknown_screening_question422An answer quotes a question the job does not have.
Quote each question exactly as the job's screeningQuestions lists it.
Permalinkinvalid_sia_license_number422The answer to an SIA license number question is not a 16-digit license number.
Send the 16 digits of the applicant's SIA license.
Permalinkinvalid_psa_license_number422The answer to a PSA license number question is not a PSA license number such as EM123456/28.
Send the number printed on the applicant's PSA license, starting with EM.
Permalinkthrottled429Too many requests reached the API in a short time.
Wait a moment, then retry with backoff.
Permalinkrate_limited429The API key made more requests than its rate limit allows.
Wait the number of seconds in the Retry-After header, then retry.
Permalinkinternal_error500Something went wrong on our side.
Retry later. If it persists, contact support and quote the correlationId.
Permalinkupstream_timeout504The operation did not finish within the 29-second API limit.
Retry once. If it keeps timing out, contact support and quote the correlationId.
Permalinkgateway_error4xx or 5xxThe API refused the request before any operation ran; the HTTP status says which kind, and detail says why.
Check the request against the reference. For a 5xx status, retry later.
Permalink
Rate limits
Alfa API keys are limited per minute. A company key may make 120 requests a minute. A platform key may make 120 requests a minute for each client company and 1,200 a minute in total. Applicant intake allows 60 requests a minute for each key and company.
Once the key and company are accepted, every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Over the limit, the API answers 429 rate_limited with a Retry-After header: wait that many seconds, then retry. Read about API keys.