Skip to main content
VirtualInterview.ai
Docs menu

Errors and rate limits

Errors come back as JSON with an error message and, on most routes, a code you can branch on. The status tells you what to do: fix the key for 401, add a scope for 403, fix the request for 400 or 422, and wait for 429. Each key is limited to a number of requests a minute.

Reference · Last checked against the product on

Error shape

Error body
{
  "error": "This needs a human-scoped key (decisions:human).",
  "code": "HUMAN_REQUIRED"
}

Branch on code where it is present and show error to people. Validation errors on the jobs, webhooks, job goal and bulk invitation routes also include a details object listing the fields that failed.

Status codes

Status codes the API returns
StatusCodeWhen
200Success. Creating a job or a webhook endpoint answers 201.
400The body is not valid JSON or fails validation on the jobs, candidates, webhooks or bulk invitation routes.
401The key is missing, wrong or revoked, or its organisation is not active.
403FORBIDDENThe key lacks a scope the call needs. The message names it.
403HUMAN_REQUIREDA move to a human-only stage without decisions:human. Approving or overriding a proposal without it answers 403 with no code.
404NOT_FOUNDNo such route, or the application, job or proposal is not in your organisation. A proposal that is no longer open answers the same way.
405METHOD_NOT_ALLOWEDA GET sent to the MCP server, which answers POST only.
409INVALID_TRANSITIONThe application cannot move from its current stage to the one you asked for, or it is already there.
409CONFLICTThe application changed while the move was applied. Read it again and retry.
409NO_INTERVIEWA scorecard was filed for an application with no interview yet.
409NO_INVITATIONAn offer draft was asked for on an application with no invitation.
409NO_PANELA schedule proposal was approved on a job with no default panel.
409Bulk invitations: the job is a draft or closed.
409REASON_REQUIREDAn override used a reason code that is not one of the accepted codes.
409INVALIDAn approved proposal could not be applied, for example because the stage changed.
422INVALIDThe fields failed validation. The message lists each field and the problem.
422REASON_REQUIREDAn override was sent with no reason code at all.
422A webhook URL was refused: not HTTPS, a non-standard port, or a private or internal address.
429RATE_LIMIT_EXCEEDEDToo many requests. Wait for the number of seconds in Retry-After.
500Something failed on our side. Retry with backoff.

Rate limits

Each API key may make 120 requests a minute per key, counted across the REST API and the MCP server. The jobs, candidates and webhook subscription routes also have a lower limit of their own. Bulk invitations use a separate, lower limit instead. Over the limit, a request answers 429:

Response
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: …
X-RateLimit-Remaining: 0
X-RateLimit-Reset: …

{ "error": "Rate limit exceeded. …", "code": "RATE_LIMIT_EXCEEDED", "retryAfter": 23 }

Wait the number of seconds in Retry-After before trying again. Limits are counted per server, so treat the figure as a ceiling, and spread bulk work out instead of sending it in a burst. Large imports belong in one importApplicants call or one bulk invitation call, not many single ones; see the API reference.

Retrying safely

  • Retry 429 and 500 with backoff. Don’t retry 4xx errors other than 429without changing the request.
  • importApplicants is safe to repeat: a candidate already on the job is counted under existing, not added twice.
  • Bulk invitations skip anyone already invited to the job, so a repeated call does not double-invite or double-charge.
  • requestSchedule queues a new scheduling job on every call. Don’t retry it blindly after a timeout; check listSchedules first.
Was this page clear?