> ## 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.

# Request- und Response-Konventionen

> Verwenden Sie konsistente URLs, Header, Medientypen, Schema-Regeln, Response-Strukturen und Verfahren für binäre Downloads.

## Basis-URL und HTTPS

Alle öffentlichen Anfragen verwenden HTTPS und beziehen sich auf folgende Basis-URL:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.jobhandy.io/v1
```

Das Segment `v1` ist Bestandteil des öffentlichen Versionsvertrags.

## Standard-Request-Header

| Header                           |              Erforderlich | Zweck                                                                       |
| -------------------------------- | ------------------------: | --------------------------------------------------------------------------- |
| `X-API-Key`                      | Bei geschützten Endpoints | Server-zu-Server-Authentifizierung                                          |
| `X-Tenant-ID`                    |                   Bedingt | Schränkt den Tenant-Kontext ein oder löst ihn auf, wo dies dokumentiert ist |
| `X-Request-ID`                   |           Nein, empfohlen | Korreliert einen einzelnen HTTP-Request-Versuch                             |
| `Content-Type: application/json` | Bei JSON-Schreibvorgängen | Deklariert den Medientyp des Request-Bodys                                  |
| `Accept: application/json`       |         Optional bei JSON | Fordert eine JSON-Repräsentation an                                         |

Unbekannte oder nicht unterstützte Header können mit `UNSUPPORTED_HEADER` abgelehnt werden.

## Verhalten von JSON-Requests

* Senden Sie UTF-8-codiertes JSON.
* Request-Schemas sind geschlossen; unbekannte Eigenschaften werden abgelehnt.
* `PATCH`-Bodies müssen mindestens eine dokumentierte Eigenschaft enthalten.
* Ausgelassene Patch-Eigenschaften bleiben unverändert.
* Eine nullable Patch-Eigenschaft kann mit JSON `null` geleert werden.
* Ein leerer String ist ein String-Wert und nicht gleichbedeutend mit `null` oder einer ausgelassenen Eigenschaft.
* Enum-Werte sind case-sensitive.
* Dokumentierte JSON-Request-Bodies besitzen eine maximale Request-Größe von 5 MiB.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "phoneNumber": null
}
```

Dies löscht eine nullable Telefonnummer. Wird `phoneNumber` weggelassen, bleibt der bestehende Wert unverändert.

## Verhalten von JSON-Responses

Erfolgreiche Ressourcen-Responses verwenden das von der jeweiligen Operation dokumentierte Schema. Collection-Responses enthalten Elemente und Seitenmetadaten entsprechend dem ressourcenspezifischen Page-Schema.

Clients müssen unbekannte Response-Eigenschaften tolerieren, da additive Felder ohne Änderung des Pfads `/v1` eingeführt werden können.

## Fehler-Envelope

Jeder öffentliche API-Fehler verwendet dieselbe Top-Level-Struktur:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The supplied API key is missing, invalid, or inactive.",
    "requestId": "018f3d9a-7dfb-7a23-b4b4-9f7e4b19d4b4"
  }
}
```

Verwenden Sie `error.code` für Programmverzweigungen, `error.message` für die Diagnose und `error.requestId` für die Korrelation.

## Binäre Responses

Download-Endpoints für Anhänge und Payroll-Dokumente geben Binär- oder Textinhalte zurück, nicht eine JSON-Ressource.

* Behandeln Sie die Dokument-ID als undurchsichtigen Identifikator.
* Verwenden Sie den Response-Header `Content-Type`, statt den Dateityp aus dem Endpoint abzuleiten.
* Verwenden Sie den Response-Dateinamen, sofern die Operation einen entsprechenden Header liefert.
* Interpretieren Sie einen Fehler-Body nicht als Datei; prüfen Sie zuerst HTTP-Status und Medientyp.
* Schützen Sie heruntergeladene Dateien, nachdem sie die API-Grenze verlassen haben.

## Request-Größenlimits

| Request-Typ                           | Limit des öffentlichen Vertrags |
| ------------------------------------- | ------------------------------: |
| Dokumentierter JSON-Write-Body        |                           5 MiB |
| Vollständiger Incident-Multipart-Body |                           5 MiB |
| Anzahl Incident-Dateien               |                 1 bis 5 Dateien |

Das Multipart-Limit gilt für den vollständigen codierten Body, nicht nur für die Summe der ursprünglichen Dateigrößen.