Skip to main content
This guide covers error codes returned by the StackOne API and common HRIS 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

​
HRIS Provider-Specific Issues

​
HiBob

ErrorCauseFix
403 ForbiddenMissing service user permissionsEnable “View selected employees’ Lifecycle sections” per HiBob guide
Fields like termination_date and employment_status may be null if “View selected employees’ Lifecycle sections” permission is missing from the service user. Ensure proper permission sets are enabled.

​
Factorial HR

ErrorCauseFix
403 ForbiddenOAuth token missing required scopesRe-authenticate with scopes: documents, employees, company_legal_entities, contracts, finance, company_locations
This applies to OAuth integrations only.

​
Personio

Salary information in employment records is only accessible if the employee has:
  • At least one Base Salary entry
  • Legal Entity selected in their profile
This is essential for retrieving pay_rate in the API response.

​
CascadeHR

Uses IRIS Cascade HR Absence API with the following limitations:
LimitationDescription
No entitlement validationSystem doesn’t check leave balances
No key person blockingCan book time off regardless of team coverage
No overlapping rulesNo validation for conflicting absences
Auto-approvalAll absences are automatically approved as admin-entered
Half-day support: Only available on start or end date via start_half_day / end_half_day fields. Cannot mark arbitrary days as half days.

​
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