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. Operations add codes of their own, such as CAPTCHA_FAILED.

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
unauthorized401
The Authorization header is missing, or its session token or API key was refused. An API key is refused when it is mistyped, revoked or expired, or sent to the wrong host.
Send a current session token or API key as Authorization: Bearer <token>. 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
TOKEN_EXPIRED401
The session token has expired.
Get a fresh session token and retry.
Permalink
INVALID_TOKEN401
The token is not valid.
Sign in again to get a new token.
Permalink
access_denied403
The token is valid, but it does not grant access to this path.
Check that you are calling the zone your token is for.
Permalink
NO_ACTIVE_ORG403
The signed-in user has no active organization.
Choose an organization in the app, then retry.
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
FORBIDDEN403
The user may not perform this operation.
Ask an organization admin for access.
Permalink
route_not_found404
No operation matches the method and path.
Check the path against the reference.
Permalink
NOT_FOUND404
The resource does not exist or is not visible to this user.
Check the id, and that it belongs to your organization.
Permalink
job_not_found404
No linked Alfa job has this id, or it belongs to another company.
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
webhook_endpoint_not_found404
No webhook endpoint is set for this key and company.
Set one with PUT /v1/integration/webhook-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
CONFLICT409
The resource is not in a state that allows the operation.
Read the resource again and retry if the action still applies.
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_only_job409
The linked Alfa job screens applicants through an AI interview, which applicant intake does not support.
Link the ATS job to an Alfa job that screens resumes, or ask the recruiter to change how the job screens applicants.
Permalink
key_name_taken409
Another active API key in the company already has this name.
Choose a different name.
Permalink
payload_too_large413
The request body is larger than the API accepts.
Send a smaller body; upload large files through the file upload operations.
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
PRECONDITION_FAILED412
The resource changed since the entity tag you sent as If-Match was read.
Read the resource again to get its current etag, then repeat your change.
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 for a request with a different path or body.
Use a new key for each distinct request.
Permalink
invalid_webhook_url422
The webhook URL is not HTTPS, or resolves to a private, loopback or link-local address.
Use an HTTPS URL 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
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
RESOURCE_EXHAUSTED429
The AI service is busy right now.
Wait a few seconds and retry.
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.

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.