Error Codes

Every error response includes a machine-readable error code. Use this code for programmatic error handling in your integration.

Error Code	HTTP Status	Description	When It Occurs
`UNAUTHORIZED`	401	API key is missing or invalid	No `X-API-Key` header, key doesn’t exist, key is revoked or expired
`IP_NOT_ALLOWED`	403	Request IP not in allowlist	IP allowlist is configured on the key and the request IP is not listed
`SCOPE_INSUFFICIENT`	403	API key lacks the required scope	The key is missing the scope needed for the requested endpoint
`FORBIDDEN`	403	Role-based access denied	A non-owner or non-admin user is accessing an admin-only endpoint, or key creator no longer has access
`API_DISABLED`	403	API access not enabled	API access is disabled for this company
`ACCOUNT_SUSPENDED`	403	Company account suspended	The company account associated with the API key is suspended
`RATE_LIMITED`	429	Too many requests	Rate limit exceeded for the endpoint’s category
`VALIDATION_ERROR`	400	Invalid request parameters	Missing required fields, invalid types, or out-of-range values
`INVALID_BODY`	400	Malformed request body	Request body is not valid JSON
`NOT_FOUND`	404	Resource not found	The candidate, job position, or webhook does not exist
`DUPLICATE_CANDIDATE`	409	Candidate email already exists	Importing or updating a candidate with an email already present in the job position
`INVALID_STATUS`	409	Status precondition failed	Attempting to invite a candidate that is not in `new` status
`INVALID_STATUS_TRANSITION`	409	Invalid status change	Attempting to select or reject a candidate not in a valid status
`ANALYSIS_NOT_VIEWED`	409	Analysis not yet viewed	Attempting to select or reject before viewing the interview analysis
`ACTIVE_SESSION`	409	Active interview session exists	Attempting to delete a candidate with an active session link without `force=true`
`WEBHOOK_LIMIT_REACHED`	409	Maximum webhooks registered	The company already has 5 active webhooks
`IDEMPOTENCY_CONFLICT`	409	Idempotency key reused with different body	The same `Idempotency-Key` was sent with a different request payload
`TELEPHONY_DISABLED`	403	Telephony not enabled for the company	The company does not have outbound calling enabled (`company.telephonyEnabled !== true`)
`ADMIN_ONLY_PARAMETER`	403	Admin-only parameter sent by an API key	`force=true` was sent on `schedule-call` by an API-key caller; it requires a Firebase admin session
`WINDOW_IN_PAST`	400	Scheduling window is in the past	The window ends in the past
`WINDOW_TOO_LONG`	400	Scheduling window too long	The scheduling window exceeds the allowed span
`WINDOW_TOO_SOON`	412	Window starts too soon	`windowStartMs` is closer than the minimum lead time
`WINDOW_TOO_SHORT_FOR_INTERVIEW`	412	Window shorter than the interview	The window is shorter than the interview duration
`WINDOW_FALLS_OUTSIDE_CALLING_HOURS`	412	Window outside calling hours	No slot in the window falls within the applied calling hours/days
`PRESET_DEADLINE_TOO_CLOSE`	412	Preset deadline too close	The chosen preset’s deadline is too close to now to fit the interview
`CANDIDATE_OUTBOUND_COOLDOWN`	412	Candidate in outbound cooldown	The candidate is in cooldown after an exhausted retry sequence
`RETRY_LIMIT_EXCEEDED`	412	Weekly retry cap reached	The candidate has reached the weekly retry cap
`WORKING_HOURS_NOT_CONFIGURED`	412	Calling hours not configured	Company calling hours must be configured before scheduling non-test candidates
`TIMEZONE_SELECTION_REQUIRED`	422	Explicit timezone required	The candidate phone maps to a multi-timezone country; supply an explicit `timezone`
`CLOCK_REJECTED`	429	No admittable capacity in window	No admittable slot in the window due to capacity; includes a `Retry-After` header
`NUMBER_AT_CAP`	429	Outbound number at capacity	The resolved number hit its per-number outbound cap; includes a `Retry-After` header
`CANDIDATE_HAS_ACTIVE_RESERVATION`	409	Candidate already has a live reservation	Scheduling against an existing live reservation without `replace`, or cancelling an in-flight reservation on the public path