Error Response Format
Errors use an RFC 7807-inspired structure wrapped in anerror envelope:
| Field | Description |
|---|---|
type | URI reference for documentation |
code | Machine-readable error code |
status | HTTP status code |
message | Human-readable summary |
details | Field-level errors (validation only) |
requestId | Unique ID for debugging |
Synchronous Error Codes
Authentication Errors
| Code | Status | Description | Action |
|---|---|---|---|
UNAUTHORIZED | 401 | Missing/invalid API key | Check your API key |
FORBIDDEN | 403 | Valid key, insufficient permissions | Contact support |
Validation Errors
| Code | Status | Description | Action |
|---|---|---|---|
VALIDATION_ERROR | 400 | Request body failed validation | Fix fields listed in details |
QUESTION_SET_NOT_FOUND | 404 | Invalid questionSetId | Use ID from /v1/criteria/questions |
ANSWER_MISMATCH | 400 | Answer doesn’t match question | Check answer ID and type |
Resource Errors
| Code | Status | Description | Action |
|---|---|---|---|
NOT_FOUND | 404 | Resource not found | Verify the ID |
Rate Limiting
| Code | Status | Description | Action |
|---|---|---|---|
RATE_LIMITED | 429 | Too many requests | Wait for Retry-After duration |
Server Errors
| Code | Status | Description | Action |
|---|---|---|---|
INTERNAL_ERROR | 500 | Unexpected error | Retry with backoff |
SERVICE_UNAVAILABLE | 503 | Temporary unavailability | Retry with backoff |
Async Scoring Error Codes
These appear in webhook payloads orGET /v1/score/{scoringJobId} responses:
| Code | Description | Action |
|---|---|---|
CRITERIA_NOT_FOUND | No active criteria for this job | Generate criteria first via /v1/criteria/generate |
RESUME_FETCH_FAILED | Could not download resume | Verify URL is accessible and not expired |
RESUME_ENCRYPTED | PDF is password-protected | Request unprotected version from candidate |
RESUME_CORRUPTED | PDF is malformed or truncated | Verify file opens correctly, re-upload if needed |
RESUME_PARSE_FAILED | Could not parse resume content | Check file format is supported |
RESUME_TOO_LARGE | File exceeds 10MB limit | Reduce file size |
RESUME_EMPTY | No extractable content | Verify file isn’t corrupted |
CRITERIA_INVALID | Malformed criteria | Verify criteria format |
AI_PROCESSING_FAILED | AI model error | Retry - usually transient |
TIMEOUT | Processing exceeded limit | Retry - may indicate complex resume |
Validation Error Details
ForVALIDATION_ERROR, the details array provides field-level information:
Detail Codes
| Code | Description |
|---|---|
REQUIRED | Field is required but missing |
TOO_SHORT | String is shorter than minimum |
TOO_LONG | String exceeds maximum |
INVALID_TYPE | Wrong data type |
INVALID_FORMAT | Wrong format (URL, UUID, etc.) |
INVALID_VALUE | Value not in allowed set |
NOT_FOUND | Referenced resource doesn’t exist |
Retry Strategy
- Retryable Errors
- Non-Retryable Errors
These errors should be retried with exponential backoff:
429 RATE_LIMITED- Wait forRetry-After500 INTERNAL_ERROR- Retry 2-3 times503 SERVICE_UNAVAILABLE- Retry 2-3 timesRESUME_FETCH_FAILED- Regenerate URL and retryAI_PROCESSING_FAILED- Retry 1-2 timesTIMEOUT- Retry once
Implementation
Debugging with Request ID
Every response includes arequestId. When contacting support:
Monitoring Recommendations
Alert on error rate spikes
Alert on error rate spikes
Track error rates by code and alert if they exceed baseline.
Monitor latency
Monitor latency
Track P50/P99 latency for early warning of issues.
Log all errors with context
Log all errors with context
Include
requestId, request body, and response for debugging.Track retry rates
Track retry rates
High retry rates may indicate configuration issues.
Common Issues
RESUME_FETCH_FAILED on valid URLs
RESUME_FETCH_FAILED on valid URLs
Causes:
- URL expired before we could fetch it
- Firewall blocking our IP range
- Certificate issues
- Set longer expiry (24h recommended)
- Whitelist our IP ranges (contact support)
- Verify SSL certificates are valid
ANSWER_MISMATCH errors
ANSWER_MISMATCH errors
Causes:
- Answer ID doesn’t match any question
- Answer type doesn’t match question type
- Using wrong questionSetId
- Verify answer IDs match question IDs exactly
- Use string for singleSelect/text, array for multiSelect
- Store and use the correct questionSetId
Sporadic 500 errors
Sporadic 500 errors
Causes:
- Transient infrastructure issues
- High load
- Implement retry with exponential backoff
- These typically resolve within seconds