---
title: "Konventionen"
description: "Paginierung, Datumsangaben, Limits und Antwortheader."
canonical: "https://atelier201.com/docs/de/api/conventions"
updated: "2026-11-06"
---

# Konventionen

## Antwortumschläge

Jede erfolgreiche Antwort hat das Format `{ "data": ..., "request_id": "..." }`. Geben Sie bei einer Problemmeldung die
`request_id` an. Anhand dieser ID lässt sich der passende Protokolleintrag finden.

## Paginierung

Immer cursorbasiert, niemals mit Offset. Übergeben Sie den `next_cursor` aus der vorherigen Antwort
als `cursor`.

Bei einem Offset wird auf jeder Seite der gesamte bisherige Bereich erneut durchlaufen. Schlimmer noch: Werden zwischen zwei Anfragen Einträge eingefügt,
überspringt die Paginierung Zeilen. Ein Client, der eine gerade bearbeitete Liste seitenweise abruft,
übersieht so unbemerkt Einträge. Mit einem Cursor passiert das nicht.

## Nachsichtige Eingaben

`limit` wird angepasst, nicht abgelehnt: Bei einer Anfrage nach 500 erhalten Sie 100, und die Antwort
nennt das angewendete Limit. Ein nicht numerischer Wert für `limit` führt weiterhin zu einem Fehler,
weil es sich dabei um einen Irrtum und nicht um eine Absicht handelt.

Datumsangaben können als `2026-07-01` oder als vollständiger ISO-8601-Zeitstempel angegeben werden. Ein reines Datum auf der
`to`-Seite steht für das ENDE dieses Tages. Das entspricht der üblichen Bedeutung von „bis zum
31.“.

## Sicher schreiben

Bei jeder Schreiboperation, die etwas ersetzt, können Sie angeben, was ersetzt werden soll. Senden Sie den
`expected_hash` einer Datei oder eines Eintrags, den Sie gelesen haben. Wurde er inzwischen geändert, wird die Änderung mit
`409 conflict` abgelehnt. Für die Veröffentlichung, das Zurücksetzen und das Zurückziehen einer Veröffentlichung benötigen Sie den Wert von
`expected_generation`, den Sie gelesen haben. So ändern Sie nur den Zustand, den Sie geprüft haben. Beide Konfliktantworten enthalten unter `error.details` die Angaben, die Sie erneut abrufen müssen.

## Lang laufende Vorgänge

Ein Build wird sofort mit dem Status `queued` zurückgegeben. Rufen Sie den Status so lange ab, bis er
`ready`, `failed` oder `cancelled` lautet. Diese Status sind endgültig. Beenden Sie die Abfragen, sobald einer davon erscheint.

## Ratenlimits

Es gelten fünf Limits, die unterschiedliche Bereiche schützen: den Durchsatz pro Zugangsdaten, kurze Lastspitzen,
das Volumen pro IP-Adresse, die Clientregistrierung und speziell FEHLGESCHLAGENE
Authentifizierungen. Jede Antwort enthält das verbleibende Kontingent in den Headern. Eine Antwort mit Status 429 enthält `Retry-After`.