Troubleshooting

API 2.0.0: active contract required

POST /incidents requires a contract with status active. Status approved is insufficient. Without an active contract, the request fails with HTTP 422 and EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, including when dryRun=true; no incident is created. Resolve the contract state through the responsible business process before submitting a new request with a new X-Request-ID. Existing incidents remain editable under their existing lifecycle and field restrictions. This new prerequisite applies to creation. The employee activation prerequisite remains documented separately; no precedence between validation errors is specified.

API 2.0.0: blocking changes and active contracts

For PATCH /employees/{id}, an active contract prohibits both blocked: true and blocked: false. If blocked is included, the API rejects the entire patch with HTTP 422 and EMPLOYEE_HAS_ACTIVE_CONTRACT, including when dryRun=true. Other fields in that rejected request are not applied. Sending the employee’s existing blocked value does not avoid this rule. For profile-only updates, omit blocked entirely. Configure serializers and synchronization mappings so they do not add blocked: false as a default. For example:

{
  "phoneNumber": "+49 221 5550199"
}

Do not retry an unchanged rejected patch. Resolve the blocking request through the responsible business process, or, for an independently intended profile update, send a new patch containing only the intended supported profile fields. A successful dry run does not reserve contract state; handle the same validation on the real write. Start with the HTTP status, error.code, and X-Request-ID. Do not repeat writes blindly while diagnosing.

Triage flow

Connectivity

Symptom	Check
DNS or connection failure	Base URL is exactly `https://api.jobhandy.io/v1`; outbound HTTPS is allowed
TLS failure	System trust store, TLS inspection, proxy configuration, and current time
`/health` fails	Network path or public service availability
`/health` works but protected read fails	API key, tenant scope, or request headers

Authentication and scope

`401 INVALID_API_KEY`

Confirm the value is loaded from the intended secret version.
Confirm there are no leading/trailing spaces or accidental quotes.
Confirm the key is active in API Key Management.
Confirm a stale runtime was not missed during rotation.

`403 TENANT_NOT_IN_SCOPE`

Confirm X-Tenant-ID is a tenant ID, not a company name or division ID.
Confirm the selected tenant is included in the key scope.
Confirm the referenced resource belongs to the same authorized context.

Ambiguous placement

Send X-Tenant-ID and, for employee creation where required, an allowed divisionId.

Request validation

Error	Check
`UNKNOWN_QUERY_PARAMETER`	Parameter name and endpoint support
`UNSUPPORTED_HEADER`	Remove non-contract request headers
`INVALID_FILTER_SYNTAX`	Quotes, escaped apostrophes, parentheses, `IN` commas
`UNSUPPORTED_FILTER_FIELD`	Endpoint-specific field list
`UNSUPPORTED_FILTER_OPERATOR`	Operator compatible with field
`UNSUPPORTED_SORT_FIELD`	Exactly one documented scalar field
`UNSUPPORTED_MEDIA_TYPE`	`application/json` or documented multipart type
`PAYLOAD_TOO_LARGE`	Complete JSON or multipart body below 5 MiB
`VALIDATION_ERROR`	Required fields, formats, enum case, nullability, unknown properties
`EMPLOYEE_NOT_ACTIVATED`	Referenced employee has not completed activation; activate the employee before creating the incident

State conflicts

For 409, re-read the resource before taking action.

ORDER_ALREADY_DECIDED: reconcile the current final decision.
INVALID_STATE_TRANSITION: current lifecycle does not permit the request.
DIVISION_CYCLE: selected parent is a descendant of the division.
DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL: choose a unique sibling name.
DUPLICATE_RESOURCE: find and map the existing resource.

Timeout after a write

Download failures

Re-read metadata and confirm fileName is not null.
Confirm the ID belongs to the expected tenant.
Inspect status and Content-Type before writing to disk.
Discard partial files after 502, 503, 504, or network interruption.
Retry transient download failures with bounded backoff.

Escalation record

Collect:

UTC timestamp
method and path
HTTP status
error.code and error.message
X-Request-ID / error.requestId
tenant context
attempt count
whether dryRun was used
sanitized reproduction steps

Never include the API key or unnecessary complete personal payloads.

Get Started

Architecture & Concepts

Integration Guides

Operations

API 2.0.0: active contract required

API 2.0.0: blocking changes and active contracts

Triage flow

Connectivity

Authentication and scope

`401 INVALID_API_KEY`

`403 TENANT_NOT_IN_SCOPE`

Ambiguous placement

Request validation

State conflicts

Timeout after a write

Download failures

Escalation record

​API 2.0.0: active contract required

​API 2.0.0: blocking changes and active contracts

​Triage flow

​Connectivity

​Authentication and scope

​401 INVALID_API_KEY

​403 TENANT_NOT_IN_SCOPE

​Ambiguous placement

​Request validation

​State conflicts

​Timeout after a write

​Download failures

​Escalation record

API 2.0.0: active contract required

API 2.0.0: blocking changes and active contracts

Triage flow

Connectivity

Authentication and scope

`401 INVALID_API_KEY`

`403 TENANT_NOT_IN_SCOPE`

Ambiguous placement

Request validation

State conflicts

Timeout after a write

Download failures

Escalation record