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_json400

    The request body is not valid JSON.

    Send a JSON body with Content-Type: application/json.

    Permalink
  • unexpected_body400

    The operation takes no request body, but one was sent.

    Send the request without a body.

    Permalink
  • unexpected_query400

    The request has query parameters the operation does not define.

    Remove the parameters listed in detail, or check their spelling.

    Permalink
  • invalid_path400

    The request path has an invalid percent-encoding.

    Percent-encode each path segment, such as an externalJobId, exactly once.

    Permalink
  • unauthorized401

    The Authorization header is missing, or its API key was refused: mistyped, revoked or expired, or sent to the wrong host.

    Send the API key as Authorization: Bearer <key>. Send alfa_live_ keys to api.welovealfa.com and alfa_test_ keys to dev-api.welovealfa.com.

    Permalink
  • invalid_cursor400

    The cursor was changed, has expired, or belongs to a list with different filters.

    Start again from the first page, without a cursor.

    Permalink
  • invalid_idempotency_key400

    The Idempotency-Key header is empty, too long or not visible ASCII.

    Send 1 to 255 visible ASCII characters, such as a UUID.

    Permalink
  • company_id_required400

    A 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_…).

    Permalink
  • access_denied403

    The API key does not grant access to this path.

    Check that the path starts /v1/integration.

    Permalink
  • platform_key_required403

    A company key called an operation only a platform key can call.

    Use your platform key for /v1/integration/platform operations.

    Permalink
  • not_a_sub_client403

    The 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.

    Permalink
  • insufficient_scope403

    The 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.

    Permalink
  • company_not_connected403

    The 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.

    Permalink
  • api_not_enabled403

    The Alfa API is not switched on for this company.

    Contact Alfa to switch it on.

    Permalink
  • account_locked403

    The company's Alfa account is locked, so the API refuses every request for it.

    Ask the company to contact Alfa.

    Permalink
  • sourcing_disabled403

    Sourcing is switched off for this company.

    Ask the company to contact Alfa about sourcing on its plan.

    Permalink
  • payment_required402

    The company's Alfa account is paused or canceled, so sourcing can't start.

    Ask the company to contact its Alfa account manager, then retry.

    Permalink
  • route_not_found404

    No operation matches the method and path.

    Check the path against the reference.

    Permalink
  • job_not_found404

    No 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.

    Permalink
  • candidate_not_found404

    No candidate has this id on a job linked to an ATS job.

    Check the candidateId, including its app_ or src_ prefix.

    Permalink
  • resume_not_available404

    The candidate has no resume, as with most sourced candidates.

    Treat the resume as missing; resumeUrl is null for these candidates.

    Permalink
  • interview_not_available404

    The 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.

    Permalink
  • webhook_endpoint_not_found404

    No webhook endpoint is set for this key and company.

    Set one with PUT /v1/integration/webhook-endpoint.

    Permalink
  • contact_check_endpoint_not_found404

    No contact check endpoint is set for this key and company.

    Set one with PUT /v1/integration/contact-check-endpoint.

    Permalink
  • delivery_not_found404

    No webhook delivery has this id for this key and company.

    Check the deliveryId against the delivery log.

    Permalink
  • method_not_allowed405

    The path exists, but not for this HTTP method.

    Use one of the methods the reference lists for the path.

    Permalink
  • ats_integration_conflict409

    The company already uses another ATS integration in Alfa.

    Ask the company to disconnect the other integration first, or contact Alfa.

    Permalink
  • job_not_accepting_applications409

    The 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.

    Permalink
  • application_in_progress409

    Another request with the same externalApplicationId is still being processed.

    Wait a moment, then retry with the same externalApplicationId.

    Permalink
  • interview_job_in_progress409

    Another request is creating the interview job for this externalJobId.

    Wait a moment, then send the same request again.

    Permalink
  • job_not_live409

    The 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.

    Permalink
  • job_not_draft409

    The 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.

    Permalink
  • publish_in_alfa409

    The 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.

    Permalink
  • job_quota_exceeded402

    The 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.

    Permalink
  • invalid_job_advert422

    The job description is blank or reads as internal instructions rather than an advert.

    Send a candidate-facing description, then publish the draft.

    Permalink
  • insufficient_sourcing_credits409

    The 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.

    Permalink
  • request_id_reused409

    The requestId already started a sourcing campaign with different credits.

    Send a new requestId for a new campaign.

    Permalink
  • sourcing_not_started409

    Alfa could not start sourcing on this job, for example a demo job.

    Check the job in Alfa, or contact Alfa.

    Permalink
  • payload_too_large413

    The request body is larger than the API accepts.

    Send a smaller body. A resume may be at most 4 MB once decoded.

    Permalink
  • idempotency_in_progress409

    A request with the same Idempotency-Key is still running.

    Wait a moment, then retry with the same key to get its result.

    Permalink
  • validation_failed422

    The 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.

    Permalink
  • idempotency_key_reused422

    The 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.

    Permalink
  • invalid_webhook_url422

    The 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.

    Permalink
  • ats_job_not_linked422

    No 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.

    Permalink
  • invalid_country422

    Alfa does not recognize the country of the job.

    Send the country by its English name or ISO code, such as United Kingdom or GB.

    Permalink
  • unsupported_country422

    Alfa does not recognize the country.

    Send the country by its English name, such as United Kingdom.

    Permalink
  • resume_required422

    The linked Alfa job screens resumes, and the request has none.

    Send the resume. Only a job that interviews applicants takes them without one.

    Permalink
  • unsupported_resume_type422

    The resume is not a PDF, Word document or plain text file.

    Send application/pdf, application/msword, the Word .docx type or text/plain.

    Permalink
  • resume_too_large422

    The decoded resume is larger than 4 MB.

    Send a smaller file.

    Permalink
  • invalid_resume422

    The 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.

    Permalink
  • screening_questions_incomplete422

    A mandatory screening question of the job has no answer.

    Read the job's screeningQuestions and send an answer to each mandatory one in screeningAnswers.

    Permalink
  • unknown_screening_question422

    An answer quotes a question the job does not have.

    Quote each question exactly as the job's screeningQuestions lists it.

    Permalink
  • invalid_sia_license_number422

    The answer to an SIA license number question is not a 16-digit license number.

    Send the 16 digits of the applicant's SIA license.

    Permalink
  • invalid_psa_license_number422

    The 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.

    Permalink
  • throttled429

    Too many requests reached the API in a short time.

    Wait a moment, then retry with backoff.

    Permalink
  • rate_limited429

    The API key made more requests than its rate limit allows.

    Wait the number of seconds in the Retry-After header, then retry.

    Permalink
  • internal_error500

    Something went wrong on our side.

    Retry later. If it persists, contact support and quote the correlationId.

    Permalink
  • upstream_timeout504

    The operation did not finish within the 29-second API limit.

    Retry once. If it keeps timing out, contact support and quote the correlationId.

    Permalink
  • gateway_error4xx or 5xx

    The 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.