Troubleshooting

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

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

​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

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