דילוג לתוכן

API

Errors.

Standard HTTP status codes, and a JSON body with a message you can show or log.

עודכן לאחרונה ב-19 בנובמבר 2026

התיעוד למפתחים זמין באנגלית בלבד.

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
{  "statusCode": 404,  "message": "Candidate not found.",  "error": "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
{  "statusCode": 400,  "message": "Validation failed.",  "issues": [    {      "path": "email",      "message": "Invalid email address"    }  ]}

Status codes

StatusMeaningExamples
400The request is invalidValidation failed; Publish the interview before inviting candidates
401No valid API keyInvalid or revoked API key; an expired key
402The plan doesn't allow itNo interview minutes left for a new invitation
403The key may not do thisA missing scope; a request from outside the IP allowlist
404Not found in your companyCandidate not found; Invitation not found; Session not found; Interview not found
409Conflicts with the current stateA candidate with this email already exists; The candidate has already started this interview; A request with this Idempotency-Key is already in progress
422The Idempotency-Key can't be usedIdempotency-Key was used with a different request body; Idempotency-Key is too long
429Too many requestsToo many requests for this API key.
500Our faultInternal 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)
503A part of the service didn't answerThe candidate service didn't answer.

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.

CodeStatusMeaning
key_missing401No Authorization: Bearer aik_live_… header
key_invalid401The key is unknown or revoked
key_expired401The key is past its expiry: extend it or create a new one
scope_missing403The key lacks the permission this route needs
ip_not_allowed403The request came from outside the key's IP allowlist
route_not_available403The route can't be called with an API key
interview_unpublished400The interview was never published: publish it before inviting
candidate_exists409Your company already has a candidate with this email: find them with GET /v1/candidates
plan_limit402The plan doesn't allow it (interview minutes used up, an interview longer than the plan allows)
idempotency_in_progress409The first request with this Idempotency-Key is still running: retry in a moment
idempotency_body_mismatch422The Idempotency-Key was used with another body: don't retry, use a new key
idempotency_key_too_long422The Idempotency-Key is over 200 characters
rate_limited429Too many requests for this key: retry after Retry-After

What to retry

  • Retry 429 after its Retry-After, and 500, 502, 503 and network errors with backoff. Send POSTs with an Idempotency-Key so a retry never creates twice.
  • Don't retry other 4xx as they are: fix the request, the key or its permissions first.