> ## Documentation Index > Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt > Use this file to discover all available pages before exploring further. # Vorfall erstellen > Meldet einen Mitarbeitervorfall für einen autorisierten und aktivierten Mitarbeiter. Die API setzt Melder und Lifecycle-Status. Mit `dryRun=true` gibt die API den projizierten Vorfall zurück, ohne ihn zu speichern. ## Auf einen Blick | Eigenschaft | Verhalten | | ------------------------ | ------------------------------------------------------------------------------------------------------- | | Authentifizierung | Erforderlich in `X-API-Key` | | Tenant-Kontext | Bedingt; der referenzierte Mitarbeiter muss innerhalb des autorisierten Scopes eindeutig auflösbar sein | | Mitarbeitervoraussetzung | Der referenzierte Mitarbeiter muss aktiviert sein | | Dry Run | Unterstützt mit `dryRun=true` | | Request-Body | `application/json`; geschlossenes Schema; maximal dokumentierte Body-Größe 5 MiB | | Response | JSON | | Primärer Erfolg | `200`, `201` | | Side Effects | Erstellt einen Vorfall und setzt Melder-/Lifecycle-Metadaten; Dry Run unterdrückt die Speicherung | | Retry-Empfehlung | Nicht blind wiederholen; den erstellten Vorfall zuerst suchen oder abgleichen | ## Betriebsverhalten Meldet einen Mitarbeitervorfall. Die API setzt Melder und Lifecycle-Status. Mit `dryRun=true` gibt die API den projizierten Vorfall zurück, ohne ihn zu speichern. * Die API setzt Melder und initialen Lifecycle-Status. * Der referenzierte Mitarbeiter muss im autorisierten Tenant-Scope sichtbar und bereits aktiviert sein. * Existiert der Mitarbeiter, ist aber noch nicht aktiviert, antwortet die API mit `422 EMPLOYEE_NOT_ACTIVATED` und erstellt keinen Vorfall. ## Voraussetzung: aktivierter Mitarbeiter Ein Vorfall kann erst erstellt werden, nachdem der referenzierte Mitarbeiter aktiviert wurde. Existiert der Mitarbeiter und ist er im API-Key-Scope sichtbar, wurde aber noch nicht aktiviert, antwortet die API wie folgt: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "error": { "code": "EMPLOYEE_NOT_ACTIVATED", "message": "The referenced employee is not activated.", "requestId": "" } } ``` Wiederholen Sie dieselbe Anfrage nicht automatisch. Schließen Sie zuerst die Aktivierung des Mitarbeiters ab und senden Sie anschließend eine neue Create-Anfrage mit einer neuen `X-Request-ID`. ## Häufige Fehler | Fehlercode | Bedeutung | | -------------------------- | --------------------------------------------------------------------- | | `VALIDATION_ERROR` | Schema- oder fachliche Validierung ist fehlgeschlagen | | `INVALID_REQUEST_ID` | `X-Request-ID` ist keine UUID v4 oder v7 | | `INVALID_API_KEY` | API-Key fehlt, ist ungültig, gelöscht oder inaktiv | | `TENANT_NOT_IN_SCOPE` | Ausgewählter Tenant liegt außerhalb des API-Key-Scopes | | `NOT_FOUND` | Ressource fehlt oder ist im Scope nicht zugänglich | | `NOT_ACCEPTABLE` | Angeforderter Response-Medientyp ist nicht verfügbar | | `INVALID_STATE_TRANSITION` | Aktueller Lifecycle-Status erlaubt die Anfrage nicht | | `PAYLOAD_TOO_LARGE` | Vollständiger Request überschreitet das dokumentierte Limit | | `UNSUPPORTED_MEDIA_TYPE` | Request-Medientyp wird nicht akzeptiert | | `INVALID_REFERENCE` | Referenzierte Ressource fehlt oder ist nicht verfügbar | | `EMPLOYEE_NOT_ACTIVATED` | Referenzierter Mitarbeiter existiert, wurde aber noch nicht aktiviert | | `RATE_LIMIT_EXCEEDED` | Rate Limit des API-Keys wurde überschritten | | `INTERNAL_SERVER_ERROR` | Unerwarteter Serverfehler | Die Response-Liste der Operation und die Seite [Fehlerbehandlung](/de/concepts/error-handling) sind für die vollständige Behandlung maßgeblich. ## Vor der Implementierung * Erzeugen und protokollieren Sie für den Versuch eine neue `X-Request-ID`. * Behandeln Sie jeden dokumentierten Response-Status. * Protokollieren Sie weder `X-API-Key` noch unnötige personenbezogene Daten. * Gleichen Sie den aktuellen Ressourcenstatus ab, bevor Sie einen mehrdeutigen Write wiederholen. Prüfen Sie den vollständigen Prozess sowie Status-, Retry- und Betriebsmuster für diese Operation. ## OpenAPI ````yaml https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.json?rev=20260902-employee-not-activated POST /incidents openapi: 3.1.0 info: title: JobHandy Public API version: 1.0.0 summary: Production API for HR, order, incident, division, and payroll integrations. description: >- Integrate HR and payroll systems with JobHandy through a versioned REST API. ## Production endpoint All public requests use `https://api.jobhandy.io/v1`. ## Core conventions - Authenticate protected operations with `X-API-Key`. - Use `X-Tenant-ID` where supported to select one tenant within the API-key scope. - Use `X-Request-ID` for end-to-end request correlation. - Validate supported writes with `dryRun=true` before applying them. - Collection endpoints support pagination, sorting, and the documented filter expression language. - Error responses use a stable JSON envelope with a machine-readable error code. Optional query and header parameters are documented but omitted from generated requests by default in the accompanying Mintlify configuration. servers: - url: https://api.jobhandy.io/v1 description: Production security: - apiKeyAuth: [] tags: - name: Employees description: Synchronize employee master data, account state, and division assignments. - name: Orders description: Read employee orders, record HR decisions, and download order documents. - name: Incidents description: Report and maintain employee incidents and upload supported attachments. - name: Divisions description: Maintain organizational divisions, hierarchy, ordering, and cost centers. - name: Payroll export documents description: List payroll export metadata and download generated payroll files. - name: Health description: Check basic public API availability without authentication. paths: /incidents: post: tags: - Incidents summary: Create an incident description: >- Reports an employee incident. The API assigns the reporter and lifecycle status. With `dryRun=true`, the API returns the projected incident without saving it. operationId: createIncident parameters: - in: query required: false name: dryRun description: >- When `true`, the API validates the request without applying the change. The operation's responses specify the returned representation. When omitted, the server uses `false`. schema: type: boolean example: true x-mint: post: - optional - 'server default: false' - not sent by default x-client-default-state: inactive - name: X-Tenant-ID description: >- If supplied, the header narrows the operation to one tenant in the API key's scope. The referenced employee must be accessible through that tenant. If omitted, the API searches the full scope and infers the tenant from the employee. In interactive clients, use the `{{tenantId}}` variable when a tenant must be selected. Keep the header disabled when tenant selection is not required. in: header required: false schema: type: string pattern: ^[0-9a-fA-F]{24}$ x-mint: post: - optional - not sent by default x-client-default-state: inactive x-default: '{{tenantId}}' - in: header name: X-Request-ID required: false description: >- Optional request identifier. If supplied, it must be a UUID v4 or v7 and is returned unchanged in every response. If omitted, the API generates one. Invalid values return `400 INVALID_REQUEST_ID`. If your client uses a `{{requestId}}` variable, refresh it with a new UUID version 4 or 7 for every HTTP request attempt. Keep the header disabled to let the API generate the request identifier. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ x-mint: post: - optional - not sent by default x-client-default-state: inactive x-default: '{{requestId}}' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncidentCreate' examples: temporaryIncident: summary: Report a temporary incident value: type: temporary employee: 68a000000000000000000001 dateFrom: '2026-07-21T00:00:00.000Z' permanentIncident: summary: Report a permanent incident value: type: permanent employee: 68a000000000000000000001 dateFrom: '2026-07-21T00:00:00.000Z' description: The JSON request body must not exceed 5,242,880 bytes. x-max-request-body-bytes: 5242880 responses: '200': content: application/json: schema: $ref: '#/components/schemas/Incident' examples: dryRunPreview: summary: Validated dry-run preview value: id: '730000000000000000000001' employeeIncidentNumber: 37 type: temporary status: reported employee: 68a000000000000000000001 reportedBy: api_key reportedAt: '2026-07-21T07:30:00.000Z' dateFrom: '2026-07-21T00:00:00.000Z' dateUntil: null createdAt: '2026-07-21T07:30:00.000Z' updatedAt: '2026-07-21T07:30:00.000Z' description: >- Dry-run validation succeeded. Returns the incident that would be created; it is not stored. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '201': content: application/json: schema: $ref: '#/components/schemas/Incident' examples: created: summary: Created incident value: id: '730000000000000000000001' employeeIncidentNumber: 37 type: temporary status: reported employee: 68a000000000000000000001 reportedBy: api_key reportedAt: '2026-07-21T07:30:00.000Z' dateFrom: '2026-07-21T00:00:00.000Z' dateUntil: null createdAt: '2026-07-21T07:30:00.000Z' updatedAt: '2026-07-21T07:30:00.000Z' description: The incident was created and is returned. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: >- The request cannot be parsed or violates the request contract. value: error: code: VALIDATION_ERROR message: The request contains an invalid value. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 invalidRequestId: summary: X-Request-ID is not UUID v4 or v7 value: error: code: INVALID_REQUEST_ID message: The supplied X-Request-ID is invalid. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The request cannot be parsed or violates the request contract. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidApiKey: summary: API key is missing, invalid, or inactive value: error: code: INVALID_API_KEY message: The supplied API key is missing, invalid, or inactive. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The X-API-Key credential is missing, invalid, or inactive. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: tenantNotInScope: summary: Selected tenant is not in the API-key scope value: error: code: TENANT_NOT_IN_SCOPE message: >- The integration does not have access to the selected tenant. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The API key does not grant access to the selected tenant. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: summary: >- The resource was not found or is outside the API key's scope. value: error: code: NOT_FOUND message: The requested resource was not found. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The resource was not found or is outside the API key's scope. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '406': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notAcceptable: summary: Accept excludes all success media types value: error: code: NOT_ACCEPTABLE message: >- The endpoint cannot produce a response in a media type accepted by the request. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The requested response media type is not supported. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidStateTransition: summary: >- The requested operation is not valid for the resource in its current state. value: error: code: INVALID_STATE_TRANSITION message: >- The requested operation is not valid for the resource in its current state. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: >- The requested change conflicts with the resource's current state or with an existing resource. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: payloadTooLarge: summary: Request body exceeds 5 MiB value: error: code: PAYLOAD_TOO_LARGE message: The request body exceeds the maximum allowed size. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The request body exceeds 5 MiB. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '415': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unsupportedMediaType: summary: Content-Type is not supported value: error: code: UNSUPPORTED_MEDIA_TYPE message: >- The request body media type is not supported by this endpoint. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The request body media type is not supported by the endpoint. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: validationError: summary: >- The request matches the contract, but a value or referenced resource fails validation. value: error: code: VALIDATION_ERROR message: The request contains an invalid value. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 invalidReference: summary: Employee cannot be used value: error: code: INVALID_REFERENCE message: The referenced employee is invalid for this request. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: >- The request matches the contract, but a value or referenced resource fails validation. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rateLimitExceeded: summary: API-key request quota exceeded value: error: code: RATE_LIMIT_EXCEEDED message: The API key request rate limit has been exceeded. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: The API key request rate limit was exceeded. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 RateLimit-Policy: description: Request quota policy expressed as an HTTP structured field. schema: type: string RateLimit: description: Current request quota availability and effective window. schema: type: string Retry-After: description: >- Seconds to wait before retrying after request-rate admission was rejected. schema: type: integer example: 60 '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalServerError: summary: Unexpected server error value: error: code: INTERNAL_SERVER_ERROR message: The request failed. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: An unexpected server error occurred. headers: X-Request-ID: description: Request identifier returned for every public API response. schema: type: string format: uuid pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 security: - apiKeyAuth: [] components: schemas: IncidentCreate: type: object properties: type: type: string enum: - temporary - permanent minLength: 1 description: Incident type. Values are case-sensitive. example: temporary employee: type: string pattern: ^[0-9a-fA-F]{24}$ description: >- Identifier of the affected employee. The employee must be accessible in the selected or inferred tenant scope. example: 68a000000000000000000001 dateFrom: type: string pattern: Z$ format: date-time minLength: 1 description: UTC timestamp from which the incident applies. example: '2026-07-21T00:00:00.000Z' description: Fields accepted when reporting an employee incident. additionalProperties: false required: - type - employee - dateFrom example: type: temporary employee: 68a000000000000000000001 dateFrom: '2026-07-21T00:00:00.000Z' Incident: type: object properties: id: type: string pattern: ^[0-9a-fA-F]{24}$ readOnly: true minLength: 1 description: Unique incident identifier. example: '730000000000000000000001' employeeIncidentNumber: type: integer readOnly: true multipleOf: 1 description: Tenant-facing numeric incident number assigned by the server. example: 37 type: type: string enum: - temporary - permanent minLength: 1 description: Incident type. Values are case-sensitive. example: temporary status: type: string enum: - reported - in_progress - completed - archived readOnly: true minLength: 1 description: Server-managed incident lifecycle status. example: reported employee: type: string pattern: ^[0-9a-fA-F]{24}$ description: Identifier of the affected employee. example: 68a000000000000000000001 reportedBy: type: string enum: - user - api_key readOnly: true minLength: 1 description: Actor category that originally reported the incident. example: api_key reportedAt: type: string pattern: Z$ format: date-time readOnly: true minLength: 1 description: UTC timestamp at which the incident was reported. example: '2026-07-21T07:30:00.000Z' dateFrom: type: string pattern: Z$ format: date-time minLength: 1 description: UTC timestamp from which the incident applies. example: '2026-07-21T00:00:00.000Z' dateUntil: type: - string - 'null' minLength: 1 pattern: Z$ format: date-time description: >- UTC timestamp until which the incident applies, or `null` while no end is set. example: null x-mint: post: - nullable createdAt: type: string pattern: Z$ format: date-time readOnly: true minLength: 1 description: UTC timestamp at which the incident record was created. example: '2026-07-21T07:30:00.000Z' updatedAt: type: string pattern: Z$ format: date-time readOnly: true minLength: 1 description: UTC timestamp of the latest incident update. example: '2026-07-21T07:30:00.000Z' description: Employee incident details. additionalProperties: false required: - id - employeeIncidentNumber - type - status - employee - reportedBy - reportedAt - dateFrom - dateUntil - createdAt - updatedAt example: id: '730000000000000000000001' employeeIncidentNumber: 37 type: temporary status: reported employee: 68a000000000000000000001 reportedBy: api_key reportedAt: '2026-07-21T07:30:00.000Z' dateFrom: '2026-07-21T00:00:00.000Z' dateUntil: null createdAt: '2026-07-21T07:30:00.000Z' updatedAt: '2026-07-21T07:30:00.000Z' ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - type: object description: Public error details. description: Machine-readable and human-readable details for the failed request. example: error: code: INVALID_API_KEY message: The supplied API key is missing, invalid, or inactive. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: Error envelope returned by every public API endpoint. required: - error ApiError: type: object properties: code: type: string example: INVALID_API_KEY description: >- Machine-readable public error code. Values are stable and case-sensitive. - `INVALID_API_KEY`: The API key is missing, invalid, inactive, or otherwise unusable. - `INVALID_REQUEST_ID`: X-Request-ID is not a valid UUID version 4 or 7. - `NOT_ACCEPTABLE`: The Accept header excludes all success media types produced by the operation. - `UNSUPPORTED_MEDIA_TYPE`: The request Content-Type is not supported by the operation. - `MISSING_ATTACHMENT`: A required multipart attachment field or file is missing. - `PAYLOAD_TOO_LARGE`: The complete request body exceeds the documented 5 MiB limit. - `UNKNOWN_QUERY_PARAMETER`: The request contains a query parameter that the operation does not accept. - `UNSUPPORTED_HEADER`: The request contains a header value or header usage that the public contract does not support. - `NOT_FOUND`: The target resource does not exist or is not visible in the caller scope. - `FILE_NOT_FOUND`: The referenced file is not available. - `BAD_GATEWAY`: A downstream file or integration service failed while processing the request. - `SERVICE_UNAVAILABLE`: The requested service is temporarily unavailable. - `GATEWAY_TIMEOUT`: A downstream operation did not complete before the timeout. - `INTERNAL_SERVER_ERROR`: An unexpected server-side error occurred. - `TENANT_CONTEXT_AMBIGUOUS`: The API cannot infer exactly one tenant from the supplied selectors and API-key scope. - `EMPLOYEE_PLACEMENT_AMBIGUOUS`: The API cannot infer one permitted employee division placement. - `TENANT_NOT_IN_SCOPE`: The selected tenant is not accessible to the API key. - `INVALID_REFERENCE_ID`: A referenced identifier is invalid for the requested operation. - `VALIDATION_ERROR`: The request is malformed or a supplied value fails contract or business validation. - `INVALID_FILTER_SYNTAX`: The filter expression cannot be parsed. - `UNSUPPORTED_FILTER_FIELD`: The filter uses a field that the operation does not expose for filtering. - `UNSUPPORTED_FILTER_OPERATOR`: The filter uses an operator that is not supported for the selected field. - `UNSUPPORTED_SORT_FIELD`: The sort field is not supported by the operation. - `UNSUPPORTED_FIELD`: The request contains a field that is not accepted by the operation. - `INVALID_REFERENCE`: A referenced resource cannot be used in the requested context or scope. - `EMPLOYEE_BLOCKED`: The requested operation cannot continue because the employee account is blocked. - `DIVISION_CYCLE`: The requested parent relationship would create a division hierarchy cycle. - `DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL`: A sibling division already uses the requested name. - `DUPLICATE_RESOURCE`: The request would create or update a resource to a value that must be unique. - `INVALID_STATE_TRANSITION`: The requested action is not permitted from the resource current lifecycle state. - `ORDER_ALREADY_DECIDED`: The order already has an HR review decision and cannot be decided again. - `RATE_LIMIT_EXCEEDED`: The API-key request quota has been exceeded. enum: - INVALID_API_KEY - INVALID_REQUEST_ID - NOT_ACCEPTABLE - UNSUPPORTED_MEDIA_TYPE - MISSING_ATTACHMENT - PAYLOAD_TOO_LARGE - UNKNOWN_QUERY_PARAMETER - UNSUPPORTED_HEADER - NOT_FOUND - FILE_NOT_FOUND - BAD_GATEWAY - SERVICE_UNAVAILABLE - GATEWAY_TIMEOUT - INTERNAL_SERVER_ERROR - TENANT_CONTEXT_AMBIGUOUS - EMPLOYEE_PLACEMENT_AMBIGUOUS - TENANT_NOT_IN_SCOPE - INVALID_REFERENCE_ID - VALIDATION_ERROR - INVALID_FILTER_SYNTAX - UNSUPPORTED_FILTER_FIELD - UNSUPPORTED_FILTER_OPERATOR - UNSUPPORTED_SORT_FIELD - UNSUPPORTED_FIELD - INVALID_REFERENCE - EMPLOYEE_BLOCKED - DIVISION_CYCLE - DIVISION_NAME_NOT_UNIQUE_ON_SAME_LEVEL - DUPLICATE_RESOURCE - INVALID_STATE_TRANSITION - ORDER_ALREADY_DECIDED - RATE_LIMIT_EXCEEDED minLength: 1 message: type: string example: The supplied API key is missing, invalid, or inactive. description: Human-readable error summary. minLength: 1 requestId: type: string example: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 description: >- Request identifier also returned in the X-Request-ID response header. pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ format: uuid minLength: 1 description: Stable public API error details. required: - code - message - requestId example: code: VALIDATION_ERROR message: The request contains an invalid value. requestId: 018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4 securitySchemes: apiKeyAuth: type: apiKey name: X-API-Key in: header description: >- JobHandy integration API key. Send the credential in the `X-API-Key` header. Treat the key as a secret and use it only from trusted server-side environments. ````