{
"error": {
"code": "VALIDATION_ERROR",
"message": "The request could not be validated.",
"requestId": "018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4"
}
}
error.code for precise handling.
Decision flow
Error catalog
| Error code | Typical HTTP class | Meaning | Client action | Retry |
|---|---|---|---|---|
INVALID_API_KEY | 401 | Key is missing, invalid, deleted, or inactive | Replace or reactivate credential | No |
INVALID_REQUEST_ID | 400 | Request ID is not UUID v4 or v7 | Generate a valid value | No |
NOT_ACCEPTABLE | 406 | Requested response representation is unavailable | Correct Accept | No |
UNSUPPORTED_MEDIA_TYPE | 415 | Request media type is not accepted | Use documented content type | No |
MISSING_ATTACHMENT | 400 / 422 | Multipart request has no required upload | Add the required uploads field | No |
PAYLOAD_TOO_LARGE | 413 | Complete request exceeds 5 MiB | Reduce JSON or multipart size | No |
UNKNOWN_QUERY_PARAMETER | 400 | Query parameter is not supported | Remove unknown parameter | No |
UNSUPPORTED_HEADER | 400 | Header is not accepted | Remove or correct header | No |
NOT_FOUND | 404 | Resource is absent or not visible in scope | Verify ID and tenant context | No |
FILE_NOT_FOUND | 404 | Referenced file is unavailable | Re-read metadata and availability | No |
TENANT_CONTEXT_AMBIGUOUS | 400 / 422 | One target tenant cannot be resolved | Send X-Tenant-ID | No |
EMPLOYEE_PLACEMENT_AMBIGUOUS | 422 | Employee placement does not resolve one allowed division | Send an allowed divisionId | No |
TENANT_NOT_IN_SCOPE | 403 | Tenant is outside key scope | Correct scope or tenant | No |
INVALID_REFERENCE_ID | 400 / 422 | Reference ID has invalid format | Use an ID returned by JobHandy | No |
INVALID_REFERENCE | 404 / 422 | Referenced resource is missing or unavailable | Re-read reference and scope | No |
VALIDATION_ERROR | 422 | Request violates schema or business validation | Correct payload | No |
INVALID_FILTER_SYNTAX | 400 / 422 | Filter cannot be parsed | Correct quoting and expression | No |
UNSUPPORTED_FILTER_FIELD | 422 | Field is not filterable | Use endpoint-supported field | No |
UNSUPPORTED_FILTER_OPERATOR | 422 | Operator is invalid for field | Use supported operator | No |
UNSUPPORTED_SORT_FIELD | 422 | Sort field is unavailable | Use documented scalar field | No |
UNSUPPORTED_FIELD | 422 | Field is not writable or selectable | Remove unsupported field | No |
EMPLOYEE_BLOCKED | 409 / 422 | Employee state prevents operation | Resolve employee status | No |
EMPLOYEE_NOT_ACTIVATED | 422 | An incident references an employee whose activation is incomplete | Activate the employee before creating the incident | No |
DIVISION_CYCLE | 409 / 422 | Parent update would create hierarchy cycle | Choose a valid parent | No |
DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL | 409 | Sibling name already exists | Use a unique sibling name | No |
DUPLICATE_RESOURCE | 409 | Uniqueness rule is violated | Locate and reconcile existing resource | No |
INVALID_STATE_TRANSITION | 409 | Requested lifecycle transition is not allowed | Re-read state and stop blind retries | No |
ORDER_ALREADY_DECIDED | 409 | HR decision is already final | Re-read and reconcile | No |
RATE_LIMIT_EXCEEDED | 429 | API-key quota is exhausted | Honor Retry-After | Yes |
BAD_GATEWAY | 502 | Upstream dependency failed | Retry safe reads/downloads only | Conditional |
SERVICE_UNAVAILABLE | 503 | Service or dependency unavailable | Backoff; reconcile writes | Conditional |
GATEWAY_TIMEOUT | 504 | Dependency timed out | Backoff; reconcile writes | Conditional |
INTERNAL_SERVER_ERROR | 500 | Unexpected server failure | Log request ID and retry only if safe | Conditional |
Diagnostic record
Store the following for every failed attempt:UTC timestamp
HTTP method
path template, not a URL containing secrets
HTTP status
error.code
error.message
error.requestId / X-Request-ID
tenant context
attempt number
logical operation ID
Troubleshooting runbook
Follow the operation-specific checks before opening a support request.