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"
}
erroris a stable machine code. Branch on this.typeis a stable URL for the kind of error. It always ends in theerrorcode.statusis the HTTP status, repeated so the body means the same thing when it is logged on its own.titleis what happened, in one short sentence.detailandmessageare the same sentence: why it happened, and what to do next.messageis the older name and stays.- Some errors add extra fields, such as
requiredorlimit.
title and detail are written for people and may be reworded at any time. Never match on them.
Status codes
| Status | Meaning |
|---|---|
200 | The call worked. On Submit candidates, still read failed. |
400 | The request is malformed or a field failed validation. |
401 | The key is missing, malformed, expired or revoked. |
403 | The key is valid but its role lacks the permission this call needs, or the call is not one an API key can make. |
404 | The thing does not exist, or this key cannot see it. We do not tell the two apart. |
409 | The 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. |
413 | Too many files or candidates in one request. |
422 | The request was understood but nothing could be done. |
429 | Too many requests. See Rate limits. |
5xx | Something went wrong on our side. Retry with backoff. |
Error codes
error | Status | Meaning |
|---|---|---|
invalid_request | 400 | A field is missing or invalid, or a file upload could not be read. message says what. |
no_files | 400 | An extract call came with no CV files. |
idempotency_key_required | 400 | Submit candidates or Create an interview needs an Idempotency-Key header. |
invalid_api_key | 401 | The key is missing, malformed, unknown, expired or revoked. All of these answer the same way on purpose. |
forbidden | 403 | The role the key acts as lacks the permission in required. A path that is not an API endpoint answers the same way. |
billing_past_due | 403 | The workspace's plan has lapsed. Reading still works. Adding candidates is paused until it is renewed. |
account_suspended | 403 | The workspace is suspended for non-payment. Every call is refused until it is renewed. |
job_not_found | 404 | No such job, or this key cannot see it. |
workflow_not_found | 404 | No such workflow, or this key cannot see it. |
template_not_found | 404 | No such template, or this key cannot see it. |
interview_not_found | 404 | No such interview, or this key cannot see it. |
job_not_active | 409 | The job is not active. job_status says what it is. Nothing was read or stored. |
job_not_interview_ready | 409 | Create 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_ready | 409 | Get an interview's report was called before the interview completed. Check status with Get an interview first. |
interview_live | 409 | Get 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_progress | 409 | A request with this Idempotency-Key has not finished. Wait, then retry with the same key. |
too_many_files | 413 | More than 10 CVs in one extract call. limit is 10. |
too_many_candidates | 413 | More than 50 candidates in one submit call. limit is 50. |
idempotency_key_reused | 422 | The same Idempotency-Key was used with a different body. |
no_candidates_created | 422 | Every row failed. details.failed lists each reason, including a single-candidate Create an interview call. |
rate_limited | 429 | Too many requests. Wait for Retry-After. retry_after is the same number in seconds. |
Retrying
- Retry
429and5xx. Wait at leastRetry-Afterseconds when it is present, and back off after that. - Do not retry
400,401,403,404or413. Fix the request first. A409 job_not_activeis worth retrying only once the job is active again, andrequest_in_progressonly after a short wait, with the same key. - When you retry a Submit candidates or Create an interview call, reuse the same
Idempotency-Keyand body.