Warum scheduled_at der Mastodon API 5 Minuten Vorlauf braucht

Was ist der minimale scheduled_at-Vorlauf in der Mastodon API?

Jeder Wert für scheduled_at der Mastodon API muss mehr als 5 Minuten vor der Uhr des Servers liegen, sonst lehnt POST /api/v1/statuses die Anfrage mit HTTP 422 ab. Die form-data-Dokumentation für diesen Endpunkt sagt es in einer Zeile: „Datetime at which to schedule a status. Providing this parameter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.“

Der Update-Endpunkt wiederholt die Regel mit leicht anderen Worten. PUT /api/v1/scheduled_statuses/:id dokumentiert sein eigenes scheduled_at als „Datetime at which the status will be published. Must be at least 5 minutes into the future“, also scheitert das Verschieben eines bestehenden geplanten Beitrags auf weniger als fünf Minuten genauso wie das Anlegen.

Die Zahl ist keine Konvention der Dokumentation. Sie ist eine Konstante im Modell, MINIMUM_OFFSET = 5.minutes.freeze in app/models/scheduled_status.rb, und die Validierung, die sie benutzt, lautet:

def validate_future_date
  errors.add(:scheduled_at, I18n.t('scheduled_statuses.too_soon')) if scheduled_at.present? && scheduled_at <= Time.now.utc + MINIMUM_OFFSET
end

Der Vergleich ist <=, also scheitert ein Zeitstempel, der genau 5 Minuten entfernt liegt. „At least 5 minutes“ in der Dokumentation bedeutet im Code strikt mehr als 5 Minuten.

Was gibt die API zurück, wenn die Zeit zu nah liegt?

Eine 422 mit einer Validierungsmeldung im Feld error. Mastodons API-Fehlerbehandlung verwandelt die Rails-Ausnahme direkt in JSON:

rescue_from ActiveRecord::RecordInvalid, Mastodon::ValidationError do |e|
  render json: { error: e.to_s }, status: 422
end

Dieser Concern liegt in app/controllers/concerns/api/error_handling.rb und wird von Api::BaseController eingebunden, also ist der Body der eigene String der Ausnahme statt eines maschinenlesbaren Codes. Es gibt keinen Fehlercode, keine Feldliste und keinen Retry-after-Hinweis; wer ihn parst, gleicht englischen Text ab.

Warum unterscheidet sich der dokumentierte Fehlerstring von dem, was Server senden?

Weil sich der Locale-String geändert hat und das Beispiel in der Dokumentation nicht. Die Seite scheduled_statuses zeigt diesen 422-Body für den Update-Endpunkt:

{
  "error": "Validation failed: Scheduled at The scheduled date must be in the future"
}

Die aktuelle config/locales/en.yml im main-Branch von mastodon/mastodon trägt eine kürzere Formulierung:

scheduled_statuses:
  over_daily_limit: You have exceeded the limit of %{limit} scheduled posts for today
  over_total_limit: You have exceeded the limit of %{limit} scheduled posts
  too_soon: date must be in the future

Rails stellt den humanisierten Attributnamen voran, also erzeugt ein aktueller Server „Validation failed: Scheduled at date must be in the future“. Das dokumentierte Beispiel trägt weiterhin den älteren Wortlaut „The scheduled date must be in the future“.

Jeder Client, der exakt auf den dokumentierten Satz abgleicht, verpasst den Fehler auf einem aktuellen Server. Gleiche stattdessen auf den Status 422 ab und darauf, dass scheduled_at in deiner eigenen Anfrage steht.

Was passiert, wenn scheduled_at in der Vergangenheit liegt?

Der Beitrag geht sofort raus, und es wird kein Fehler ausgelöst. Das ist das Verhalten, das die Dokumentation nie erwähnt, und es steckt in PostStatusService:

@scheduled_at = @options[:scheduled_at]&.to_datetime
@scheduled_at = nil if scheduled_in_the_past?

mit

def scheduled_in_the_past?
  @scheduled_at.present? && @scheduled_at <= Time.now.utc
end

@scheduled_at auf nil zu setzen macht scheduled? falsch, was die Anfrage über process_status! statt über schedule_status! leitet. Die Antwort ist eine Status-Entität, keine ScheduledStatus, also liest ein Client, der annimmt, scheduled_at liefere immer eine ScheduledStatus, eine fehlende id für einen Beitrag, der bereits öffentlich ist.

Drei Ergebnisse, ein Parameter:

Das mittlere Band ist die Falle. Eine Retry-Schleife, die einen fehlgeschlagenen Versand „ein paar Minuten später“ noch einmal probiert, läuft in die 422; eine, die auf „dann eben sofort posten“ zurückfällt und einen vergangenen Zeitstempel sendet, bekommt einen Live-Beitrag statt des erwarteten Fehlers.

Wie viele geplante Statusmeldungen kann ein Konto halten?

Zwei weitere Limits sitzen im selben Modell neben dem Offset, und keines davon steht in der API-Dokumentation:

TOTAL_LIMIT = 300
DAILY_LIMIT = 25
MINIMUM_OFFSET = 5.minutes.freeze

TOTAL_LIMIT begrenzt, wie viele geplante Statusmeldungen ein Konto gleichzeitig in der Warteschlange haben kann, und die Meldung lautet „You have exceeded the limit of 300 scheduled posts“. DAILY_LIMIT begrenzt, wie viele sich ein einzelnes Kalenderdatum teilen können, validiert mit scheduled_at::date = ?::date gegen die Datenbank, und die Meldung lautet „You have exceeded the limit of 25 scheduled posts for today“.

Beide kommen in derselben 422-Form an, mit der Meldung auf base statt auf scheduled_at. Eine Warteschlange, die einen Monat an Beiträgen in einem Lauf lädt, trifft die Wand von 25 pro Tag lange vor den 300 insgesamt, und nichts auf docs.joinmastodon.org warnt vor einer der beiden.

Welches Format hat scheduled_at?

Ein Datum mit Uhrzeit nach RFC 3339, das Mastodon separat als sein Datetime-Format dokumentiert: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[s][TZD], wobei der Zeitzonen-Bezeichner entweder Z für UTC oder ein Offset wie +02:00 ist. Die Dokumentation ist ausdrücklich darin, dass der Trenner ein großes T ist und dass Z immer großgeschrieben wird.

Die Validierung vergleicht gegen Time.now.utc auf dem Server, nicht auf dem Client. Abweichungen der Client-Uhr fressen daher direkt an der Fünf-Minuten-Marge, was ein guter Grund ist, auf sechs oder sieben Minuten zu planen statt auf fünf Minuten und eine Sekunde. Dasselbe Fehlermuster taucht überall dort auf, wo eine Warteschlange der lokalen Zeit vertraut, etwa bei Mastodon und Bluesky und jeder anderen API, die gegen ihre eigene Uhr validiert.

Wie änderst oder stornierst du eine geplante Statusmeldung?

Drei Endpunkte verwalten die Warteschlange nach dem Anlegen. GET /api/v1/scheduled_statuses listet sie auf, standardmäßig mit 20 Ergebnissen und maximal 40. PUT /api/v1/scheduled_statuses/:id nimmt ein neues scheduled_at an und unterliegt derselben 5-Minuten-Regel. DELETE /api/v1/scheduled_statuses/:id storniert eine und gibt ein leeres Objekt zurück.

Den Text zu ändern ist eine andere Operation. Mastodon merkt an, dass PUT /api/v1/statuses/:id einen veröffentlichten Status bearbeitet, und dass gilt: „To edit the scheduled_at attribute of a ScheduledStatus to change the publication date, use the scheduled status endpoint.“ Der Inhalt eines eingereihten Beitrags liegt im params-Objekt der ScheduledStatus-Entität, und der Update-Endpunkt nimmt nur das Datum an, also heißt eine Änderung des Wortlauts löschen und neu anlegen.

Eine eingereihte Statusmeldung, die nicht mehr existiert, gibt 404 mit {"error": "Record not found"} zurück, und dasselbe kommt für eine geplante Statusmeldung, die zu einem anderen Konto gehört.

Was bedeutet die 5-Minuten-Untergrenze für eine Posting-Warteschlange?

Sie setzt den kürzesten sinnvollen Abstand zwischen der Entscheidung zu posten und dem Posten selbst. Alles unter fünf Minuten muss als sofortiger Status statt als geplanter gesendet werden, also braucht ein Scheduler eine Verzweigung und keinen einzelnen Codepfad: unterhalb der Schwelle scheduled_at weglassen und veröffentlichen, oberhalb einreihen und die zurückgegebene ScheduledStatus-id speichern.

Zwei weitere Zahlen gehören in denselben Planungsdurchgang. Mastodons Standardlänge für Beiträge sind 500 Zeichen, behandelt in dem Mastodon-Zeichenlimit, und das Rate-Limiting pro Server liegt über allem, so wie Bluesky seine eigenen API-Rate-Limits getrennt von seinen Beitragsregeln veröffentlicht. Den Kalender um die Untergrenze der Plattform herum zu bauen statt um die Vorlieben eines Tools ist die allgemeine Gewohnheit hinter zuverlässigem Planen von Social-Media-Beiträgen.

Ein Vorbehalt gilt für jede Zahl weiter oben. Die Konstanten stammen aus dem main-Branch von mastodon/mastodon, und ein Server, der einen Fork oder ein älteres Release fährt, kann andere Werte tragen, also lies den 422-Body, statt anzunehmen, dass 5, 25 und 300 überall gelten.

Häufig gestellte Fragen

Nimmt scheduled_at eine Zeit an, die genau 5 Minuten in der Zukunft liegt?

Nein. Die Validierung vergleicht mit <=, also scheitert scheduled_at <= Time.now.utc + 5.minutes. Die dokumentierte Formulierung „at least 5 minutes in the future“ bedeutet strikt mehr als fünf Minuten, sobald man den Quellcode liest.

Welchen HTTP-Status gibt Mastodon für ein zu frühes scheduled_at zurück?

422. Mastodon fängt ActiveRecord::RecordInvalid ab und rendert { error: e.to_s } mit Status 422, also ist der Body ein einfacher englischer Validierungssatz statt eines strukturierten Fehlerobjekts.

Welche Mastodon-Version hat scheduled_at eingeführt?

2.7.0. Die Versionshistorie in der Dokumentation zu POST /api/v1/statuses führt „2.7.0 - scheduled_at added“ auf, und die drei scheduled_statuses-Endpunkte kamen im selben Release dazu.

Gibt ein geplanter Beitrag einen Status oder einen ScheduledStatus zurück?

Einen ScheduledStatus, immer wenn scheduled_at angenommen wird. Mastodon schreibt zu dem Endpunkt: „Returns: Status. When scheduled_at is present, ScheduledStatus is returned instead.“ Ein vergangener Zeitstempel ist die Ausnahme, weil der Server den Parameter verwirft, sofort veröffentlicht und einen Status zurückgibt.

Kannst du mehr als 25 Mastodon-Beiträge für denselben Tag planen?

Nicht auf einem Standard-Server. DAILY_LIMIT = 25 in app/models/scheduled_status.rb zählt bestehende geplante Statusmeldungen mit demselben Datum und lehnt die sechsundzwanzigste mit „You have exceeded the limit of 25 scheduled posts for today“ ab. Ein separates TOTAL_LIMIT = 300 begrenzt die gesamte Warteschlange. Keine der beiden Zahlen steht in der API-Dokumentation.

Wo ist das 5-Minuten-Minimum dokumentiert?

Auf der Seite der statuses-API-Methoden unter docs.joinmastodon.org/methods/statuses/, im form-data-Parameter scheduled_at, und noch einmal auf docs.joinmastodon.org/methods/scheduled_statuses/ für den Update-Endpunkt. Die Konstante dahinter ist MINIMUM_OFFSET = 5.minutes.freeze in app/models/scheduled_status.rb im Repository mastodon/mastodon.

Wie viele Ergebnisse liefert GET /api/v1/scheduled_statuses standardmäßig?

Zwanzig. Der Endpunkt liefert standardmäßig 20 geplante Statusmeldungen pro Seite und maximal 40, sodass ein Konto nahe am Gesamtlimit von 300 mehrere Anfragen braucht, um die ganze Warteschlange durchzublättern.

Was passiert, wenn du eine bereits stornierte geplante Statusmeldung abrufst?

Der Server antwortet mit 404 und {"error": "Record not found"}. Das ist dieselbe Antwort wie bei einer geplanten Statusmeldung, die einem anderen Konto gehört, sodass ein 404 hier nicht zwischen "nie existiert", "bereits storniert" und "gehört dir nicht" unterscheidet.

Kannst du den Text einer geplanten Mastodon-Statusmeldung bearbeiten?

Eine Textänderung bedeutet, die geplante Statusmeldung zu löschen und eine neue anzulegen, nicht sie an Ort und Stelle zu bearbeiten. Der Update-Endpunkt akzeptiert nur ein neues scheduled_at, und der Inhalt einer wartenden Statusmeldung steckt im params-Objekt der ScheduledStatus-Entität.

Wie weit im Voraus solltest du eine Mastodon-Statusmeldung tatsächlich planen?

Mehr als fünf Minuten, wobei sechs oder sieben Minuten sicherer sind als fünf Minuten und eine Sekunde. Die Prüfung läuft gegen die Uhr des Servers, nicht die des Clients, also frisst jede Abweichung der lokalen Zeit direkt von diesem Spielraum.