Skip to main content
​
type
string
invalid_request_error
​
status
number
409

​
What happened

The candidate_alias you provided is already in use. candidate_alias values are globally unique — no two candidates across any account can share the same value. 
{
  "error": {
    "type": "invalid_request_error",
    "code": "CANDIDATE_ALIAS_CONFLICT",
    "message": "A candidate with candidate_alias \"019a3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d\" already exists",
    "status": 409,
    "doc_url": "https://done.mintlify.app/errors/candidate-uuid-conflict"
  }
}

​
How to fix

Use a different candidate_alias for the new candidate. If you want idempotent creation — creating the candidate only if it doesn’t already exist — check for a 409 response and treat it as a success if the existing candidate belongs to your account.

​
Common causes

If your request timed out and you retried with the same candidate_alias, the first request may have already succeeded. Fetch GET /v1/candidates/:candidate_alias to confirm.
candidate_alias values are permanent — even after a candidate reaches a terminal state (CONFIRMED or FAILED), its candidate_alias cannot be reused. Generate a fresh UUID for each new candidate.