Errors

A request that fails as a whole is answered with an HTTP status of 400 or above and an error body:

{ "error": { "code": "invalid_credentials", "message": "Username or password is incorrect." } }

Field	Meaning
error.code	Machine-readable code from the table below. Clients decide by this value (and the HTTP status), never by the message.
error.message	Text for the user in the language of Accept-Language, named in Content-Language.

Rejected changes inside a successful push are not errors; they are reported per change with status: "rejected" (see Push).

The body is the same for every endpoint below /lve, including unknown addresses. A HEAD request gets the status without a body.

Codes

Status	Code	Emitted for	English message	German message
400	malformed_request	A body declared as JSON that does not parse	The request is not valid JSON.	Die Anfrage ist kein gültiges JSON.
400	invalid_cursor	pull with a cursor this server did not issue	The sync position is unknown. Please synchronise again from the start.	Der Synchronisationsstand ist unbekannt. Bitte neu von vorn synchronisieren.
401	unauthenticated	Missing, unknown, revoked or replaced token	Not signed in.	Nicht angemeldet.
401	invalid_credentials	auth/token with an unknown user or a wrong password	Username or password is incorrect.	Benutzername oder Passwort ist falsch.
401	invalid_pairing_code	auth/pair with an unknown, used or expired code	The pairing code is unknown, already used or expired.	Der Kopplungscode ist unbekannt, schon benutzt oder abgelaufen.
403	forbidden	Not used by the reference server in version 1; reserved for servers with permissions	This action is not allowed.	Diese Aktion ist nicht erlaubt.
404	not_found	Unknown attachment, unknown number range key, unknown address	Not found.	Nicht gefunden.
405	method_not_allowed	A method the address does not support	This method is not supported for this address.	Diese Methode wird für diese Adresse nicht unterstützt.
409	conflict	Not used by the reference server in version 1	The request conflicts with the current state.	Die Anfrage passt nicht zum aktuellen Stand.
413	payload_too_large	Attachment above 20 MiB	The upload is too large. At most 20 MB are allowed.	Die Datei ist zu groß. Erlaubt sind höchstens 20 MB.
422	validation_failed	A request field is missing, has the wrong type or is out of range	The first validation message, for example "The device ID field is required."	for example "Geräte-ID muss angegeben werden."
422	too_many_changes	push with more than 500 changes	At most 500 changes can be sent per request.	Pro Anfrage sind höchstens 500 Änderungen erlaubt.
422	hash_mismatch	Attachment whose SHA-256 differs from the path	The uploaded data does not match its SHA-256 checksum.	Die hochgeladenen Daten passen nicht zu ihrer SHA-256-Prüfsumme.
429	too_many_requests	Rate limit reached	Too many requests. Please wait a moment.	Zu viele Anfragen. Bitte warten Sie einen Moment.
other 4xx	request_failed	Any other client error	The request could not be processed.	Die Anfrage konnte nicht verarbeitet werden.
5xx	server_error	Any server failure	Internal server error.	Interner Serverfehler.

The set of codes may grow within version 1. A client that receives an unknown code handles it by its HTTP status.

Rejection messages

The message of a rejected change uses the same localisation:

Reason	English	German
invalid_change (not an object)	The change must be a JSON object.	Die Änderung muss ein JSON-Objekt sein.
invalid_change (upsert without data)	An upsert needs data as JSON object.	Ein Upsert braucht Daten als JSON-Objekt.
invalid_change (delete with data)	A delete must not carry data.	Ein Delete darf keine Daten enthalten.
invalid_change, invalid_payload (field rules)	The first validation message, naming the field
immutable	Movements cannot be deleted. Correct a wrong booking with a counter-booking.	Buchungen können nicht gelöscht werden. Korrigieren Sie eine falsche Buchung mit einer Gegenbuchung.
locked	Your company sets this template on the server. It cannot be changed in the app.	Diese Vorlage gibt Ihr Unternehmen auf dem Server vor. Sie kann in der App nicht geändert werden.

Language selection

The server picks the language from Accept-Language among the languages it supports (de and en on the reference server), using the usual quality rules (en-GB,en;q=0.9,de;q=0.8 gives en). Without the header, or when no supported language matches, the reference server answers in German. It names the chosen language in Content-Language on every response.

How clients react

Status	Client reaction
400 invalid_cursor	Discard the cursor and pull from the start
400 other	A client bug; report it and do not retry the same request
401	Stop syncing, keep local data, ask the user to sign in again
404 on HEAD attachment	Upload the attachment
404 on GET attachment	Try again on a later round; the uploading device may not have synced yet
404 on reserve	The server has no number ranges; use device numbering
413	The attachment cannot be synced; tell the user
422	A client bug or a configuration problem; show the message
429	Wait for Retry-After and retry
5xx, network errors	Treat as temporary and retry on the next round

The reference app shows error.message for every error status except 401, which it shows as "signed out", and treats transport failures (no connection, timeout) as "offline".