Errors and limits
Every error code the API returns, and the request limits and caps that apply.
This page is generated from the error registry and the limit settings, so it matches what the API does.
Error format
Every failure has the same shape. API concepts shows an example.
| Field | Meaning |
|---|---|
type | The class of failure. It matches the HTTP status. |
code | The specific reason. Branch on code, never on message. |
message | A sentence for people. It can change. |
param | The field or parameter at fault, or null. |
requestId | The same value as the X-Request-Id header. Quote it to support. |
docUrl | A link to the code on this page. |
Some errors add a field. existingId is the ID of the record that already exists, on a duplicate. matchedOn says what matched. price and maxCredits are on price_exceeds_max.
Request limits
| Limit | Value |
|---|---|
| Requests per key | 600 reads and 120 writes per minute |
| Requests per workspace | 1,200 reads and 240 writes per minute |
| Requests per IP address | 600 per minute; 30 per minute for invalid keys |
| Request body | 64 KB of JSON |
| Page size | 1 to 100, 25 by default |
| Idempotency keys | Replay for 24 hours |
Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the tightest window. A 429 or 503 also carries Retry-After in seconds. Wait at least that long before you retry.
Caps
| Cap | Value | What happens at the cap |
|---|---|---|
| Reports running at once | 50 per workspace, shared with the app | New reports from the API wait as queued and start when there is room. The app refuses instead. |
| Resume file size | 10 MB, PDF or DOCX | invalid_parameter |
| Files waiting to be attached | 100 per workspace; each expires after 24 hours | too_many_pending_files |
| Webhook endpoints | 5 per workspace | webhook_endpoint_limit |
| Searches | 120 per minute per key, on top of the request limits | rate_limit_exceeded |
| Talent searches | One running at a time for a job; a finished one is reused for 7 days unless you send refresh | The existing search is returned with reused: true |
| Test events | 5 per minute per endpoint | rate_limit_exceeded |
| Invitation emails | 3 per interview per hour, including resends from the app | resend_limit_exceeded |
| Events feed and delivery history | 30 days | event_cursor_expired for an old cursor |
| Active API keys | 10 per workspace | Revoke one before you create another |
Invalid request
Type invalid_request.
invalid_request
HTTP 400. The request is invalid.
auto_invite_apply_not_allowed
HTTP 400. applyToExisting is only allowed when the save switches the rule on or loosens it. Send it with a rule that is off, or with criteria that are no stricter than the current ones.
max_credits_required
HTTP 400. Applying an invite rule to existing reports can spend credits. Send maxCredits, at least the credits in the preview's applyQuote.
invalid_json
HTTP 400. The request body is not valid JSON.
invalid_content_type
HTTP 400. Send the request body as application/json.
request_body_too_large
HTTP 400. The request body is larger than 64 KB.
unknown_field
HTTP 400. The request contains a field that this endpoint does not accept.
invalid_cursor
HTTP 400. The cursor is invalid, expired or belongs to a different query.
invalid_idempotency_key
HTTP 400. The Idempotency-Key header must be 1 to 255 visible ASCII characters.
method_not_allowed
HTTP 405. This endpoint does not support this HTTP method.
invalid_parameter
HTTP 422. A parameter is missing or has an invalid value.
file_not_uploaded
HTTP 422. The file has not been uploaded yet. PUT the file to the upload URL, then try again.
file_rejected
HTTP 422. The uploaded file is not a valid PDF or DOCX resume.
file_expired
HTTP 422. The file expired before it was attached. Upload it again.
candidate_resume_missing
HTTP 422. The candidate has no resume. Add one with PUT /v1/candidates/{id}/resume, then create the report.
candidate_resume_failed
HTTP 422. Probb could not read the candidate's resume. Replace it with PUT /v1/candidates/{id}/resume, then create the report.
candidate_email_missing
HTTP 422. Probb has no email address for this candidate. Send email, or add one to the candidate.
unknown_event_type
HTTP 400. The event type is not one of the event types in the webhook events reference.
invalid_webhook_url
HTTP 400. Use an HTTPS URL on port 443, on the public Internet, without credentials or a fragment.
event_cursor_expired
HTTP 410. The cursor is older than the 30 days events are kept, so events may have been missed. Start again without after.
unprocessable_request
HTTP 422. The request cannot be processed in the current state.
version_not_available
HTTP 422. This version is not available to the organization. Choose one from available in the organization settings.
final_round_unsupported
HTTP 422. A final round cannot be prepared from this report. reason says why: the report's analysis has not finished, its version has no final-round support, it has no requirements, or it is not linked to a saved candidate and job.
final_round_invalid_selection
HTTP 422. The requirements, questions or assignments do not make a valid final round. Preview the report to see its requirement keys.
candidate_kit_unsupported
HTTP 422. Candidate feedback cannot be drafted from this report. reason says why: the report's analysis has not finished, its version has no feedback support, it has no requirements, or it is not linked to a saved candidate and job.
candidate_kit_no_email
HTTP 422. The candidate has no email address on file, so the feedback cannot be emailed. Release it with channel: link and share the link yourself, or add the address to the candidate first.
candidate_kit_empty
HTTP 422. There is nothing to send: every section is off or every item is removed. Turn a section on or restore an item with PATCH /v1/reports/{id}/candidate-kit.
candidate_kit_invalid_edit
HTTP 422. The edit cannot be applied. reason says why: the item is not in the draft, an item is repeated, the text is empty or too long, or the note is too long.
interviewer_not_member
HTTP 422. Every interviewer must be a member of the organisation. Viewers may interview.
external_is_member
HTTP 422. An address in externals belongs to a member of the organization. Give that person to assignments by user ID instead.
scorecard_invalid_item
HTTP 422. An entry names an item that is not part of your assignment. Use the key of the requirements and questions in your part of the final round.
scorecard_incomplete
HTTP 422. A scorecard needs every item rated (not_covered counts) and an overall lean before it can be submitted. unrated says how many items are missing a rating.
scorecard_reason_required
HTTP 422. Changing a submitted scorecard needs a revisionReason of 1 to 500 characters.
Authentication
Type authentication.
| Code | HTTP | Returned by |
|---|---|---|
authentication_required | 401 | every endpoint |
invalid_api_key | 401 | every endpoint |
authentication_required
HTTP 401. Send your API key as a Bearer token in the Authorization header.
invalid_api_key
HTTP 401. The API key is invalid, expired or revoked.
Permission
Type permission.
| Code | HTTP | Returned by |
|---|---|---|
insufficient_scope | 403 | every endpoint |
api_access_disabled | 403 | every endpoint |
webhooks_not_enabled | 403 | createWebhookEndpoint, testWebhookEndpoint |
auto_invite_admin_required | 403 | setJobAutoInvite |
permission_denied | 403 | 22 endpoints |
not_an_interviewer | 403 | putFinalRoundScorecard |
candidate_feedback_disabled | 403 | draftCandidateKit, updateCandidateKit, redraftCandidateKit, releaseCandidateKit, draftJobCandidateKits, releaseJobCandidateKits |
insufficient_scope
HTTP 403. This API key does not have the scope this endpoint requires.
api_access_disabled
HTTP 403. API access is turned off for this organisation. An organisation admin can turn it on in Settings, Developer.
webhooks_not_enabled
HTTP 403. Outbound webhooks are turned off for this organisation. An organisation admin can turn them on in Settings, Developer.
auto_invite_admin_required
HTTP 403. Only an admin or owner can switch a rule to invite automatically, change its wait, raise its cap or edit a rule that invites. Use a key created by an admin, with the auto_invite:manage scope.
permission_denied
HTTP 403. You do not have permission to do this.
not_an_interviewer
HTTP 403. The key's owner is not an interviewer on this final round, so there is no scorecard for them to fill in.
candidate_feedback_disabled
HTTP 403. An admin turned off candidate feedback in Settings. Drafting, editing and sending are refused until it is turned on again with PATCH /v1/organization/settings; reading a draft and revoking a link still work, and links already released keep working until revoked or expired.
Not found
Type not_found.
route_not_found
HTTP 404. No endpoint matches this path.
resource_not_found
HTTP 404. The resource was not found.
candidate_not_found
HTTP 404. The candidate was not found.
job_not_found
HTTP 404. The job was not found.
report_not_found
HTTP 404. The report was not found.
interview_not_found
HTTP 404. The interview was not found.
integrity_issue_not_found
HTTP 404. The report has no data integrity finding with that ID.
follow_up_not_found
HTTP 404. The report has no follow-up question with that ID.
final_round_not_found
HTTP 404. No final round has been prepared for this report.
external_interviewer_not_found
HTTP 404. The final round has no outside interviewer with that assignment ID.
auto_invite_rule_not_found
HTTP 404. This job has no auto-invite rule. Set one with PUT /v1/jobs/{id}/auto-invite.
auto_invite_evaluation_not_found
HTTP 404. One or more of the auto-invite items were not found on this job.
candidate_kit_not_found
HTTP 404. No candidate feedback has been drafted for this report.
decision_not_found
HTTP 404. No decision has been recorded for this candidate and job.
talent_search_not_found
HTTP 404. The talent search was not found.
activity_not_found
HTTP 404. The activity was not found.
file_not_found
HTTP 404. The file was not found or has expired.
webhook_endpoint_not_found
HTTP 404. The webhook endpoint was not found.
webhook_delivery_not_found
HTTP 404. The webhook delivery was not found.
event_not_found
HTTP 404. The event was not found or is past its retention period.
resume_not_found
HTTP 404. This candidate has no resume file to download.
Conflict
Type conflict.
idempotency_key_reused
HTTP 409. This Idempotency-Key was already used with a different request body or by a different API key.
idempotency_request_in_progress
HTTP 409. A request with this Idempotency-Key is still being processed. Retry shortly.
resource_conflict
HTTP 409. The request conflicts with the current state of the resource.
revision_mismatch
HTTP 412. The resource changed since you read it. Fetch it again and retry with the new revision.
candidate_exists
HTTP 409. A candidate with this external ID or email already exists. Its ID is in existingId; send allowDuplicate to create another with the same email.
job_exists
HTTP 409. A job with this external ID already exists. Its ID is in existingId.
report_exists
HTTP 409. A report for this candidate and job, or with this external ID, already exists. Its ID is in existingId.
final_round_exists
HTTP 409. A final round already exists for this report. Its ID is in existingId.
final_round_locked
HTTP 409. An interviewer has already submitted a scorecard, so this final round can no longer be changed.
final_round_cancelled
HTTP 409. This final round was cancelled. Send it again with PUT to prepare it afresh.
final_round_completed
HTTP 409. This final round is complete and cannot be cancelled.
final_round_not_active
HTTP 409. This final round is complete or cancelled, so outside interviewers' links no longer open.
external_resend_too_soon
HTTP 409. An invitation went out in the last minute. Wait a minute before sending another.
external_link_not_active
HTTP 409. The link is revoked or has expired. Send a new link first.
candidate_kit_warnings
HTTP 409. Some of the feedback's wording reads like a score, a rejection reason or a teammate's name. Edit it, or send the request again with acknowledgeWarnings: true once a person has seen it. GET /v1/reports/{id}/candidate-kit lists the warnings.
candidate_kit_not_released
HTTP 409. This candidate feedback has not been released, or its link was revoked, so there is no link to revoke or repeat.
scorecard_submitted
HTTP 409. This scorecard is already submitted. Send a revisionReason to change it.
scorecard_not_submitted
HTTP 409. This scorecard has not been submitted yet, so there is nothing to revise.
already_decided
HTTP 409. Someone already decided on this identity review. List the open ones with GET /v1/identity-reviews.
auto_invite_not_pending
HTTP 409. One or more of these items are not waiting for approval. List the queue with GET /v1/jobs/{id}/auto-invite/evaluations?outcome=queued.
auto_invite_not_held
HTTP 409. One or more of these items are not waiting to be invited automatically. List the held invites with GET /v1/jobs/{id}/auto-invite/evaluations?outcome=held.
auto_invite_not_restorable
HTTP 409. One or more of these items cannot be put back: only candidates dismissed by the same user in the last few minutes can be restored.
job_closed
HTTP 409. The job is closed, so it takes no new reports. Reopen it first with POST /v1/jobs/{id}/reopen.
job_not_indexed
HTTP 409. The job is still being prepared for talent search. Try again in a few minutes.
report_not_reviewable
HTTP 409. Only a report that needs review can be reviewed, and this one does not.
report_not_completed
HTTP 409. Only a completed report can be interviewed against. Wait for report.completed, or review it first if it needs review.
interview_exists
HTTP 409. This report already has an interview. Its ID is in existingId; send replaceExisting to replace it.
interview_in_progress
HTTP 409. An interview the candidate is taking cannot be replaced.
interview_not_resendable
HTTP 409. The invitation can only be re-sent while the candidate has not started and the interview has not expired, failed or been cancelled.
interview_not_cancellable
HTTP 409. Only an interview the candidate has not started can be cancelled.
interview_scoring_not_failed
HTTP 409. Only an interview whose scoring failed can be retried. This one is being scored or was scored.
merge_work_in_progress
HTTP 409. Probb is still working on one of these records (reading a resume, preparing a profile or job, analysing, or searching talent). Merge once the work has finished.
merge_not_ready
HTTP 409. One of these records cannot be merged yet: it is still being added, or (for jobs) it is closed. Finish adding it or reopen the job, then merge.
integrity_issue_already_resolved
HTTP 409. This data integrity finding has already been reviewed.
integrity_issue_not_resolved
HTTP 409. This data integrity finding is already open.
webhook_endpoint_limit
HTTP 409. The organisation already has 5 webhook endpoints. Delete one before adding another.
webhook_endpoint_paused
HTTP 409. The webhook endpoint is paused. Set its status to active with PATCH /v1/webhook-endpoints/{id}.
secret_rotation_in_progress
HTTP 409. The previous secret is still valid from the last rotation. Rotate again when its 24-hour overlap has ended.
delivery_not_retryable
HTTP 409. Only a finished delivery whose event is still retained can be retried, and only while its endpoint is active.
file_already_attached
HTTP 409. This file is already attached to a candidate. Upload it again to reuse it.
too_many_pending_files
HTTP 409. The organisation has 100 files waiting to be attached. Attach them or wait for them to expire after 24 hours.
Payment required
Type payment_required.
insufficient_credits
HTTP 402. The organisation does not have enough credits for this action.
quota_exceeded
HTTP 402. The organisation's monthly limit has been reached.
price_exceeds_max
HTTP 402. The current price is higher than the maxCredits you allowed. It is in the price field.
quote_exceeds_max_credits
HTTP 402. Applying the rule to existing reports could cost more than the maxCredits you allowed. The most it could cost is in the credits field.
Rate limit
Type rate_limit.
| Code | HTTP | Returned by |
|---|---|---|
rate_limit_exceeded | 429 | every endpoint |
resend_limit_exceeded | 429 | resendInterview |
rate_limit_exceeded
HTTP 429. Too many requests. Retry after the time in the Retry-After header.
resend_limit_exceeded
HTTP 429. This invitation was already re-sent 3 times in the last hour. Try again later.
Server error
Type api_error.
| Code | HTTP | Returned by |
|---|---|---|
api_error | 500 | every endpoint |
service_unavailable | 503 | every endpoint |
inbox_unavailable | 503 | 8 endpoints |
maintenance_mode | 503 | 60 endpoints |
api_error
HTTP 500. Something went wrong on our side. Retry, and contact support if it persists.
service_unavailable
HTTP 503. The service is temporarily unavailable. Retry shortly.
inbox_unavailable
HTTP 503. Email forwarding is not set up on this deployment, so there are no forwarding addresses or inbound emails.
maintenance_mode
HTTP 503. Probb is read-only for maintenance. Reads still work; retry writes later.