The error body
A 2xx status means success. Anything else carries a JSON body whose message says what went wrong, in plain English.
404 Not Found
A request body that fails validation is a 400 with issues: the path of each field and what's wrong with it.
400 Bad Request
Status codes
| Status | Meaning | Examples |
|---|---|---|
400 | The request is invalid | Validation failed; Publish the interview before inviting candidates |
401 | No valid API key | Invalid or revoked API key; an expired key |
402 | The plan doesn't allow it | No interview minutes left for a new invitation |
403 | The key may not do this | A missing scope; a request from outside the IP allowlist |
404 | Not found in your company | Candidate not found; Invitation not found; Session not found; Interview not found |
409 | Conflicts with the current state | A candidate with this email already exists; The candidate has already started this interview; A request with this Idempotency-Key is already in progress |
422 | The Idempotency-Key can't be used | Idempotency-Key was used with a different request body; Idempotency-Key is too long |
429 | Too many requests | Too many requests for this API key. |
500 | Our fault | Internal server error (the details are only in our logs: write to hello@testee.ai with the response's X-Request-Id, and we find them) |
503 | A part of the service didn't answer | The candidate service didn't answer. |
Note
An id from another company is always a
404, never a 403: the API doesn't confirm that someone else's data exists.Error codes
Where you need to tell refusals with the same status apart, the body has a stable code. Branch on it, never on message, whose wording may change.
| Code | Status | Meaning |
|---|---|---|
key_missing | 401 | No Authorization: Bearer aik_live_… header |
key_invalid | 401 | The key is unknown or revoked |
key_expired | 401 | The key is past its expiry: extend it or create a new one |
scope_missing | 403 | The key lacks the permission this route needs |
ip_not_allowed | 403 | The request came from outside the key's IP allowlist |
route_not_available | 403 | The route can't be called with an API key |
interview_unpublished | 400 | The interview was never published: publish it before inviting |
candidate_exists | 409 | Your company already has a candidate with this email: find them with GET /v1/candidates |
plan_limit | 402 | The plan doesn't allow it (interview minutes used up, an interview longer than the plan allows) |
idempotency_in_progress | 409 | The first request with this Idempotency-Key is still running: retry in a moment |
idempotency_body_mismatch | 422 | The Idempotency-Key was used with another body: don't retry, use a new key |
idempotency_key_too_long | 422 | The Idempotency-Key is over 200 characters |
rate_limited | 429 | Too many requests for this key: retry after Retry-After |
What to retry
- Retry
429after itsRetry-After, and500,502,503and network errors with backoff. Send POSTs with anIdempotency-Keyso a retry never creates twice. - Don't retry other
4xxas they are: fix the request, the key or its permissions first.