Skip to main content

Errors

Every error, from every endpoint, is an RFC 9457 problem details object, sent as application/problem+json:

{
"type": "https://docs.tarkflo.com/concepts/errors#forbidden",
"title": "This key cannot do that",
"status": 403,
"detail": "The role this key acts as does not include it. Change the key's role in Settings, API keys.",
"error": "forbidden",
"message": "The role this key acts as does not include it. Change the key's role in Settings, API keys.",
"required": "candidates:create"
}
  • error is a stable machine code. Branch on this.
  • type is a stable URL for the kind of error. It always ends in the error code.
  • status is the HTTP status, repeated so the body means the same thing when it is logged on its own.
  • title is what happened, in one short sentence.
  • detail and message are the same sentence: why it happened, and what to do next. message is the older name and stays.
  • Some errors add extra fields, such as required or limit.

title and detail are written for people and may be reworded at any time. Never match on them.

Status codes​

StatusMeaning
200The call worked. On Submit candidates, still read failed.
400The request is malformed or a field failed validation.
401The key is missing, malformed, expired or revoked.
403The key is valid but its role lacks the permission this call needs, or the call is not one an API key can make.
404The thing does not exist, or this key cannot see it. We do not tell the two apart.
409The request conflicts with the current state: a job that is not active, a job not set up for the call you made, a retry still in flight, or an interview that is not in the state the call needs.
413Too many files or candidates in one request.
422The request was understood but nothing could be done.
429Too many requests. See Rate limits.
5xxSomething went wrong on our side. Retry with backoff.

Error codes​

errorStatusMeaning
invalid_request400A field is missing or invalid, or a file upload could not be read. message says what.
no_files400An extract call came with no CV files.
idempotency_key_required400Submit candidates or Create an interview needs an Idempotency-Key header.
invalid_api_key401The key is missing, malformed, unknown, expired or revoked. All of these answer the same way on purpose.
forbidden403The role the key acts as lacks the permission in required. A path that is not an API endpoint answers the same way.
billing_past_due403The workspace's plan has lapsed. Reading still works. Adding candidates is paused until it is renewed.
account_suspended403The workspace is suspended for non-payment. Every call is refused until it is renewed.
job_not_found404No such job, or this key cannot see it.
workflow_not_found404No such workflow, or this key cannot see it.
template_not_found404No such template, or this key cannot see it.
interview_not_found404No such interview, or this key cannot see it.
job_not_active409The job is not active. job_status says what it is. Nothing was read or stored.
job_not_interview_ready409Create an interview needs a job whose workflow opens with an AI interview round. Use Submit candidates for a job with a different pipeline.
interview_not_ready409Get an interview's report was called before the interview completed. Check status with Get an interview first.
interview_live409Get a fresh interview link was called while the candidate is interviewing. Reissuing a link would end their session. Try again once it finishes.
request_in_progress409A request with this Idempotency-Key has not finished. Wait, then retry with the same key.
too_many_files413More than 10 CVs in one extract call. limit is 10.
too_many_candidates413More than 50 candidates in one submit call. limit is 50.
idempotency_key_reused422The same Idempotency-Key was used with a different body.
no_candidates_created422Every row failed. details.failed lists each reason, including a single-candidate Create an interview call.
rate_limited429Too many requests. Wait for Retry-After. retry_after is the same number in seconds.

Retrying​

  • Retry 429 and 5xx. Wait at least Retry-After seconds when it is present, and back off after that.
  • Do not retry 400, 401, 403, 404 or 413. Fix the request first. A 409 job_not_active is worth retrying only once the job is active again, and request_in_progress only after a short wait, with the same key.
  • When you retry a Submit candidates or Create an interview call, reuse the same Idempotency-Key and body.