Errors, rate limits and retries

RFC 2119 keywords apply.

Error envelope

Every non-2xx response has this envelope:

{
  "error": "requirements_rejected",
  "message": "One or more requirements cannot be used as written.",
  "rejected": [ ... ],
  "warnings": [ ... ]
}

string

required

Stable machine code. Branch on this, never on message.

string

required

A human sentence in the request language. You MAY show it to the recruiter where this documentation says so; otherwise log it.

varies

Depend on the code (listed below).

A malformed JSON body or a request that does not match the schema returns a 4xx whose error code is not fixed in v1; handle it by HTTP status and log message. Any error code not listed on this page MUST be handled by its HTTP status.

Error codes

Cross-cutting errors (any endpoint)

HTTP	`error`	Meaning	What to do
401	`invalid_partner_key`	`x-partner-key` missing or not recognized.	Check your key configuration. Do not retry.
401	`invalid_org_token`	`x-vort-org` missing or not recognized.	The customer must reconnect: show your “Connect Vort” screen again.
403	`partner_disabled`	Your partner account is disabled.	Contact Vort. Do not retry.
403	`organization_disabled`	This customer’s connection is disabled.	Tell the customer admin their Vort connection is paused; contact Vort.
429	`rate_limited`	Too many requests. Carries `Retry-After`.	Wait `Retry-After` seconds, then retry.
503	`rate_limit_unavailable`	Vort could not verify your request quota, so the request was not run.	Retry with backoff (nothing was executed).
5xx	(any)	Vort-side failure.	Retry with backoff where the endpoint is safe to retry (see Idempotency).

Error codes by endpoint

Endpoint	HTTP	`error`	Extra fields
`POST /activations/redeem`	404	`code_not_found`	—
	409	`code_already_redeemed`	`redeemed_at`
	410	`code_expired`	—
	409	`external_id_taken`	—
`POST /users`	422	`invalid_user`	—
`POST /jobs`	422	`job_rejected`	`rejected[]` (JobIssue)
`POST /runs`	422	`requirements_rejected`	`rejected[]`, `warnings[]` (RequirementIssue)
	404	`job_not_found`	—
	404	`user_not_found`	—
`GET /runs/{run_id}`	404	`run_not_found`	—
`POST .../reveal`	402	`insufficient_credits`	`balance`, `required`
	404	`candidate_not_in_run`	—
	404	`run_not_found`	—
`POST .../decisions`	422	`unknown_reject_reason`	`allowed[]`
	422	`invalid_decision`	—
	404	`run_not_found`	—

JobIssue and RequirementIssue are described under Objects.acting_user_external_id on reveal and decisions must name a user you registered with POST /users; an unknown user is rejected with 404 user_not_found, as on POST /runs.A run that exists but belongs to another customer organization returns 404 run_not_found, never 403. Runs are only visible to the organization whose token started them.

Rate limits

Limits are per partner (all your customers together), not per customer.
Defaults: 120 requests per minute and 20,000 requests per day. Vort may adjust them per partner by agreement.
Over the limit you get 429 rate_limited with Retry-After: <seconds>. You MUST wait at least that long before retrying. Do not retry in a tight loop.
Every request counts, including failed ones and requests still in progress (a burst of concurrent requests is counted as it arrives).
If Vort cannot verify your quota at that moment, the request is refused with 503 rate_limit_unavailable and nothing is executed; retry with backoff.

Budgeting guidance: polling one run every 5 seconds costs 12 requests per minute. Poll from your server once per run (not once per open browser tab), fan the result out to your clients, stop polling when the run reaches a terminal status, and use the run_completed / run_failed webhooks instead of polling runs no recruiter is looking at.

Idempotency and retries

v1 has no Idempotency-Key header. Each endpoint’s behavior on a repeated call:

Endpoint	Repeat with the same input	Safe to retry after a timeout?
`POST /activations/redeem`	Single-use. A second redeem of the same code returns `409 code_already_redeemed` with `redeemed_at`; the org token is not returned again.	No. If the first response was lost, ask Vort for a new activation code.
`POST /users`	Upsert on `external_id` within the organization. Returns the same `user_id`, `created: false`.	Yes.
`POST /jobs`	Upsert on `external_id` within the organization. A repeat call updates `title`, `description_text` and `location_text` and returns the same `job_id` with `created: false, updated: true`. Send it whenever the job changes in your ATS, so the next run uses the current description. Runs already started keep the description they started with.	Yes.
`POST /runs`	Not idempotent. Every accepted call starts a new run.	No. Do not retry automatically on a timeout or 5xx. Show the recruiter an error with a manual “Try again” action. A `422`/`404` created nothing and may be retried after fixing the input.
`GET /runs/{run_id}`	Read-only.	Yes.
`POST .../reveal`	A candidate already revealed for this organization MUST NOT be charged again; the repeat returns the contact details with `credits_charged: 0`.	Yes.
`POST .../decisions`	Each `(run_id, candidate_id, decision, occurred_at)` is stored once. A retry resends the same `occurred_at` and is counted in `duplicates`. A later action on the same candidate, including a note added afterwards, carries a new `occurred_at` and is kept as a new history entry. `notices_shown` codes are stored once per run.	Yes, when `occurred_at` is reused on retry.

Retry policy for retry-safe calls: exponential backoff starting at 1 s, max 3 attempts, honoring Retry-After on 429. Never retry 401, 403, 404, 409, 410, 422.

Testing error handling in the sandbox

Send x-vort-sandbox-simulate: rate_limited, rate_limit_unavailable, internal_error (or insufficient_credits) on a sandbox request to force the matching error response (429 with Retry-After: 30, 503, 500, 402). See Simulating errors. The sandbox also has a few error codes of its own, such as 422 sandbox_limit and 429 sandbox_run_quota; they are listed under Sandbox-only codes and headers.

Get started

Build the integration

Errors, rate limits and retries

Error envelope

Error codes

Rate limits

Idempotency and retries

Testing error handling in the sandbox

​Error envelope

​Error codes

​Rate limits

​Idempotency and retries

​Testing error handling in the sandbox

Error envelope

Error codes

Rate limits

Idempotency and retries

Testing error handling in the sandbox