Interface, responses and troubleshooting

This page describes the interface for machine data in detail. For the message formats, see Sending measured values and Sending process data. The OpenAPI reference of the endpoint: Machine data API reference.

Endpoint

POST https://<sot-host>/data-ingest/api/v1/tenants/{tenantId}/ingest

{tenantId} is the ID of your tenant. It must match the tenant of the access token.

Headers

Header Value Description

Header	Value	Description
`Authorization`	`Bearer <access token>`	Access token of a technical client with the permission `measurements:write`. See Authentication.
`Content-Type`	`application/json`	Other content types are rejected with `415`.
`X-Message-Type`	`measurement` or `process`	Type of the message. See Sending measured values and Sending process data.
`X-Api-Version`	`1.0`	Version of the message format.

Authorization

Bearer <access token>

Access token of a technical client with the permission measurements:write. See Authentication.

Content-Type

application/json

Other content types are rejected with 415.

X-Message-Type

measurement or process

Type of the message. See Sending measured values and Sending process data.

X-Api-Version

1.0

Version of the message format.

Responses

Status Error code Meaning and reaction

Status	Error code	Meaning and reaction
`202 Accepted`	–	The message was stored and will be processed.
`400 Bad Request`	`ERR_UNSUPPORTED_MESSAGE_TYPE`, `ERR_MISSING_API_VERSION`, `ERR_MISSING_BODY`, `ERR_INVALID_JSON`, `ERR_SCHEMA_VALIDATION`	The request or the message is invalid. Correct the request. Do not retry unchanged.
`401 Unauthorized`	`ERR_UNAUTHORIZED`	The access token is missing or invalid. Get a new token.
`403 Forbidden`	`ERR_FORBIDDEN`	The token does not contain `measurements:write`, or the tenant of the token does not match `{tenantId}`.
`413 Content Too Large`	`ERR_PAYLOAD_TOO_LARGE`	The request is larger than 1 MiB. Split the data into several requests.
`415 Unsupported Media Type`	`ERR_UNSUPPORTED_CONTENT_TYPE`	`Content-Type` is not `application/json`.
`429 Too Many Requests`	`ERR_CAPACITY_EXCEEDED`	The service is busy. Retry after the seconds in the `Retry-After` header (1 second).
`503 Service Unavailable`	`ERR_OUTBOX_FULL`, `ERR_STORAGE`	The service cannot store the message right now. Retry later. For `ERR_OUTBOX_FULL`, wait the seconds in the `Retry-After` header (60 seconds).

202 Accepted

–

The message was stored and will be processed.

400 Bad Request

ERR_UNSUPPORTED_MESSAGE_TYPE, ERR_MISSING_API_VERSION, ERR_MISSING_BODY, ERR_INVALID_JSON, ERR_SCHEMA_VALIDATION

The request or the message is invalid. Correct the request. Do not retry unchanged.

401 Unauthorized

ERR_UNAUTHORIZED

The access token is missing or invalid. Get a new token.

403 Forbidden

ERR_FORBIDDEN

The token does not contain measurements:write, or the tenant of the token does not match {tenantId}.

413 Content Too Large

ERR_PAYLOAD_TOO_LARGE

The request is larger than 1 MiB. Split the data into several requests.

415 Unsupported Media Type

ERR_UNSUPPORTED_CONTENT_TYPE

Content-Type is not application/json.

429 Too Many Requests

ERR_CAPACITY_EXCEEDED

The service is busy. Retry after the seconds in the Retry-After header (1 second).

503 Service Unavailable

ERR_OUTBOX_FULL, ERR_STORAGE

The service cannot store the message right now. Retry later. For ERR_OUTBOX_FULL, wait the seconds in the Retry-After header (60 seconds).

Error responses have the following format:

{
  "code": "ERR_SCHEMA_VALIDATION",
  "message": "measurementTimeSeries: minItems constraint violated",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Include the traceId when you contact support.

Delivery behavior

Every accepted request is processed at least once. In rare cases, a message can be processed twice, for example after a restart.
If you send the same message twice, it is processed twice. Avoid sending messages again after a 202 Accepted.
The order of messages of one tenant and message type is preserved.

Troubleshooting

Problem Solution

Problem	Solution
`401 Unauthorized`	The token is missing or expired. Request a new token.
`403 Forbidden`	The client does not have `measurements:write`, or the tenant in the URL does not match the token.
`400` with `ERR_SCHEMA_VALIDATION`	The message does not match the format. The `message` field names the invalid field.
`202`, but no values in the chart	Check that `reference.identifier` matches the technical ID and that `name` matches a measuring point of the device exactly (case-sensitive). Check the time range of the chart.
Values appear with a delay	Messages are processed asynchronously. Wait a few seconds and refresh.

401 Unauthorized

The token is missing or expired. Request a new token.

403 Forbidden

The client does not have measurements:write, or the tenant in the URL does not match the token.

400 with ERR_SCHEMA_VALIDATION

The message does not match the format. The message field names the invalid field.

202, but no values in the chart

Check that reference.identifier matches the technical ID and that name matches a measuring point of the device exactly (case-sensitive). Check the time range of the chart.

Values appear with a delay

Messages are processed asynchronously. Wait a few seconds and refresh.

Schnittstelle, Antworten und Fehlerbehebung

Diese Seite beschreibt die Schnittstelle für Maschinendaten im Detail. Die Nachrichtenformate beschreiben Messwerte senden und Prozessdaten senden. Die OpenAPI-Referenz des Endpunkts: Referenz der Maschinendaten-API.

Endpunkt

POST https://<sot-host>/data-ingest/api/v1/tenants/{tenantId}/ingest

{tenantId} ist die ID des Tenants. Sie muss mit dem Tenant des Zugriffstokens übereinstimmen.

Header

Header Wert Beschreibung

Header	Wert	Beschreibung
`Authorization`	`Bearer <access token>`	Zugriffstoken eines technischen Clients mit der Berechtigung `measurements:write`. Siehe Authentifizierung.
`Content-Type`	`application/json`	Andere Content-Types lehnt der Dienst mit `415` ab.
`X-Message-Type`	`measurement` oder `process`	Typ der Nachricht. Siehe Messwerte senden und Prozessdaten senden.
`X-Api-Version`	`1.0`	Version des Nachrichtenformats.

Authorization

Bearer <access token>

Zugriffstoken eines technischen Clients mit der Berechtigung measurements:write. Siehe Authentifizierung.

Content-Type

application/json

Andere Content-Types lehnt der Dienst mit 415 ab.

X-Message-Type

measurement oder process

Typ der Nachricht. Siehe Messwerte senden und Prozessdaten senden.

X-Api-Version

1.0

Version des Nachrichtenformats.

Antworten

Status Fehlercode Bedeutung und Reaktion

Status	Fehlercode	Bedeutung und Reaktion
`202 Accepted`	–	Die Nachricht ist gespeichert und wird verarbeitet.
`400 Bad Request`	`ERR_UNSUPPORTED_MESSAGE_TYPE`, `ERR_MISSING_API_VERSION`, `ERR_MISSING_BODY`, `ERR_INVALID_JSON`, `ERR_SCHEMA_VALIDATION`	Die Anfrage oder die Nachricht ist ungültig. Die Anfrage korrigieren. Nicht unverändert wiederholen.
`401 Unauthorized`	`ERR_UNAUTHORIZED`	Das Zugriffstoken fehlt oder ist ungültig. Ein neues Token abrufen.
`403 Forbidden`	`ERR_FORBIDDEN`	Das Token enthält `measurements:write` nicht, oder der Tenant des Tokens stimmt nicht mit `{tenantId}` überein.
`413 Content Too Large`	`ERR_PAYLOAD_TOO_LARGE`	Die Anfrage ist größer als 1 MiB. Die Daten auf mehrere Anfragen aufteilen.
`415 Unsupported Media Type`	`ERR_UNSUPPORTED_CONTENT_TYPE`	`Content-Type` ist nicht `application/json`.
`429 Too Many Requests`	`ERR_CAPACITY_EXCEEDED`	Der Dienst ist ausgelastet. Nach Ablauf der Sekunden aus dem Header `Retry-After` (1 Sekunde) erneut senden.
`503 Service Unavailable`	`ERR_OUTBOX_FULL`, `ERR_STORAGE`	Der Dienst kann die Nachricht derzeit nicht speichern. Später erneut senden. Bei `ERR_OUTBOX_FULL` die Sekunden aus dem Header `Retry-After` (60 Sekunden) abwarten.

202 Accepted

–

Die Nachricht ist gespeichert und wird verarbeitet.

400 Bad Request

ERR_UNSUPPORTED_MESSAGE_TYPE, ERR_MISSING_API_VERSION, ERR_MISSING_BODY, ERR_INVALID_JSON, ERR_SCHEMA_VALIDATION

Die Anfrage oder die Nachricht ist ungültig. Die Anfrage korrigieren. Nicht unverändert wiederholen.

401 Unauthorized

ERR_UNAUTHORIZED

Das Zugriffstoken fehlt oder ist ungültig. Ein neues Token abrufen.

403 Forbidden

ERR_FORBIDDEN

Das Token enthält measurements:write nicht, oder der Tenant des Tokens stimmt nicht mit {tenantId} überein.

413 Content Too Large

ERR_PAYLOAD_TOO_LARGE

Die Anfrage ist größer als 1 MiB. Die Daten auf mehrere Anfragen aufteilen.

415 Unsupported Media Type

ERR_UNSUPPORTED_CONTENT_TYPE

Content-Type ist nicht application/json.

429 Too Many Requests

ERR_CAPACITY_EXCEEDED

Der Dienst ist ausgelastet. Nach Ablauf der Sekunden aus dem Header Retry-After (1 Sekunde) erneut senden.

503 Service Unavailable

ERR_OUTBOX_FULL, ERR_STORAGE

Der Dienst kann die Nachricht derzeit nicht speichern. Später erneut senden. Bei ERR_OUTBOX_FULL die Sekunden aus dem Header Retry-After (60 Sekunden) abwarten.

Fehlerantworten haben folgendes Format:

{
  "code": "ERR_SCHEMA_VALIDATION",
  "message": "measurementTimeSeries: minItems constraint violated",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Bei Anfragen an den Support die traceId angeben.

Zustellverhalten

Jede angenommene Anfrage wird mindestens einmal verarbeitet. In seltenen Fällen wird eine Nachricht zweimal verarbeitet, zum Beispiel nach einem Neustart.
Eine zweimal gesendete Nachricht wird auch zweimal verarbeitet. Nachrichten nach einem 202 Accepted nicht erneut senden.
Die Reihenfolge der Nachrichten eines Tenants und eines Nachrichtentyps bleibt erhalten.

Fehlerbehebung

Problem Lösung

Problem	Lösung
`401 Unauthorized`	Das Token fehlt oder ist abgelaufen. Ein neues Token anfordern.
`403 Forbidden`	Der Client hat die Berechtigung `measurements:write` nicht, oder der Tenant in der URL passt nicht zum Token.
`400` mit `ERR_SCHEMA_VALIDATION`	Die Nachricht entspricht nicht dem Format. Das Feld `message` nennt das ungültige Feld.
`202`, aber keine Werte im Diagramm	Prüfen, ob `reference.identifier` mit der technischen ID und `name` exakt mit einem Messpunkt des Geräts übereinstimmt (Groß- und Kleinschreibung beachten). Den Zeitraum des Diagramms prüfen.
Werte erscheinen verzögert	Die Verarbeitung der Nachrichten erfolgt asynchron. Einige Sekunden warten und die Ansicht aktualisieren.

401 Unauthorized

Das Token fehlt oder ist abgelaufen. Ein neues Token anfordern.

403 Forbidden

Der Client hat die Berechtigung measurements:write nicht, oder der Tenant in der URL passt nicht zum Token.

400 mit ERR_SCHEMA_VALIDATION

Die Nachricht entspricht nicht dem Format. Das Feld message nennt das ungültige Feld.

202, aber keine Werte im Diagramm

Prüfen, ob reference.identifier mit der technischen ID und name exakt mit einem Messpunkt des Geräts übereinstimmt (Groß- und Kleinschreibung beachten). Den Zeitraum des Diagramms prüfen.

Werte erscheinen verzögert

Die Verarbeitung der Nachrichten erfolgt asynchron. Einige Sekunden warten und die Ansicht aktualisieren.

Diese Seite bearbeiten Edit this page