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 |