Skip to main content
This guide covers error codes returned by the StackOne API and common ATS provider-specific issues.

​
HTTP Error Codes

All StackOne API errors follow a consistent response format: 
{
  "statusCode": 400,
  "message": "Human-readable error message",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "errorCode": "ValidationError",
  "provider_errors": []
}
CodeNameDescription
400Bad RequestInvalid request parameters or malformed request body
401UnauthorizedMissing or invalid API key, or expired credentials
403ForbiddenValid credentials but insufficient permissions
404Not FoundResource does not exist or was deleted
408Request TimeoutRequest took too long to complete
409ConflictRequest conflicts with current resource state
412Precondition FailedLinked account belongs to a disabled integration
422Unprocessable EntityRequest validation failed
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected server error
501Not ImplementedFeature not supported for this provider
502Bad GatewayError from upstream provider

​
ATS Provider-Specific Issues

​
Teamtailor

ErrorCauseFix
501 Bad RequestAPI key missing permissionsAsk customer to re-authenticate per Teamtailor guide
The hired_at field for candidates indicates when they entered the “Hired” stage in Teamtailor.

​
Greenhouse

ErrorCauseFix
404 Not FoundInvalid Greenhouse user ID provided during account linkingAsk customer to re-authenticate per Greenhouse guide

​
Lever

ErrorCauseFix
400 Invalid RequestMissing or malformed parameterCheck request parameters against documentation
401 UnauthorizedInvalid credentials or insufficient scopesRe-verify integration credentials per Lever guide
403 ForbiddenAccount settings block operationContact Lever Super Admin to update API settings
429 Too Many RequestsRate limit exceededUse SDK retryConfig or implement retry strategy
500 Server ErrorLever server errorContact StackOne support
503 Service UnavailableLever maintenance downtimeRetry with exponential backoff
The updated_after filter evaluates any candidate record change, not just specific fields. The updated_at field reflects only selected field updates. Filtering by updated_at values is unsupported.

​
SmartRecruiters

SmartRecruiters implements restrictive rate limits (1 request per 5 minutes for some endpoints) and doesn’t support listing applications/interviews directly. Default behavior: The interview endpoint filters to candidates in INTERVIEW, OFFERED, HIRED, or TRANSFERRED status only. Candidates with status REJECTED, WITHDRAWN, LEAD, or IN_REVIEW are excluded.

​
Bullhorn

Bullhorn has relaxed validation that can cause silent failures:
ScenarioBehavior
Invalid candidate_id for notesNote created but remains invisible in UI
Missing author_id for notesDefaults to API user ID

​
Workable

Candidates created without an associated application are added to a generic talent pool. These candidates will not appear in API responses as the provider doesn’t support returning talent pool candidates.

​
Debugging Tips

  1. Check Request Logs: View detailed request/response logs in Dashboard → Logs
  2. Inspect provider_errors: The raw provider response is included for 4xx/5xx errors
  3. Use the Playground: Test actions interactively to isolate issues
  4. Verify Permissions: Many 403 errors are due to missing provider-side permissions

Request Logs

View and debug API requests in the dashboard