Dokumentation

API: Fehler

Fehlerform, Statuscodes und stabile Codes der öffentlichen API.

Jeder Fehler kommt als JSON. Das Feld code ist stabil und für Programme gedacht. Das Feld message ist deutsch und für Menschen formuliert. details ist optional.

json

{
  "code": "invalid_title",
  "message": "Ein Titel ist erforderlich."
}

Statuscodes

Status	Bedeutung
400	Die Anfrage ist ungültig. Meist ein Feld oder ein JSON-Problem.
401	Kein gültiger API-Schlüssel.
403	Der Plan erlaubt die Aktion nicht oder die Rolle fehlt.
404	Die Ressource wurde nicht gefunden.
405	Diese Methode ist für die Ressource nicht erlaubt.
409	Die Aktion passt nicht zum aktuellen Zustand.
413	Der Rumpf ist größer als 1 MiB.
429	Zu viele Anfragen. `Retry-After` beachten.
500	Interner Fehler.
503	Der Dienst ist vorübergehend nicht verfügbar.

Codes

Code	Status	Bedeutung
invalid_json	400	Kein gültiges JSON.
unknown_field	400	Ein Feld im Rumpf ist unbekannt. `details.field` nennt den Namen.
request_too_large	413	Der Rumpf ist größer als 1 MiB.
invalid_title	400	Titel fehlt oder ist zu lang.
invalid_start_at	400	Beginn fehlt oder ist kein RFC-3339-Zeitpunkt.
invalid_end_at	400	Ende ist ungültig oder liegt vor dem Beginn.
invalid_timezone	400	Zeitzone fehlt oder ist keine IANA-Zeitzone.
invalid_location_type	400	Ortstyp ist nicht offline, online oder hybrid.
invalid_visibility	400	Sichtbarkeit ist nicht public oder private.
invalid_status	400	Status ist nicht draft oder published, oder der Statusfilter ist ungültig.
invalid_capacity	400	Kapazität ist negativ.
invalid_category	400	Kategorie ist unbekannt.
invalid_tags	400	Zu viele Schlagworte oder ein Schlagwort ist zu lang.
no_changes	400	Die Änderung enthält kein Feld.
invalid_days	400	Der Zeitraum liegt nicht zwischen 1 und 365 Tagen.
invalid_limit	400	Ein `limit` ist ungültig, etwa keine ganze Zahl oder außerhalb des erlaubten Bereichs.
idempotency_conflict	409	Derselbe Idempotency-Key wurde mit einem anderen Rumpf verwendet.
event_has_registrations	409	Ein veröffentlichtes Event mit Anmeldungen lässt sich nicht löschen. `details.count` nennt die Zahl der Anmeldungen.
invalid_api_key	401	Der Schlüssel fehlt, ist unbekannt oder wurde zurückgezogen.
auth_unavailable	503	Der Schlüssel konnte nicht geprüft werden.
plan_required	403	Die Aktion erfordert Eventwerk Plus.
forbidden	403	Die Rolle erlaubt die Aktion nicht.
event_not_found	404	Das Event wurde nicht gefunden.
ticket_not_found	404	Die Ticketart wurde nicht gefunden.
registration_not_found	404	Die Anmeldung wurde nicht gefunden.
not_found	404	Die Route existiert nicht.
method_not_allowed	405	Die Methode ist für diese Route nicht erlaubt.
rate_limited	429	Mehr als 200 Anfragen pro Minute je Schlüssel und Instanz.
internal_error	500	Interner Fehler.
service_unavailable	503	Der Dienst ist vorübergehend nicht verfügbar.

Weitere Codes

Code	Status	Bedeutung
invalid_webhook_url	400	Die Webhook-Adresse ist keine gültige http- oder https-Adresse.
webhook_not_found	404	Der Webhook wurde nicht gefunden.
invalid_name	400	Der Name des API-Schlüssels ist leer oder zu lang.
key_limit_reached	400	Es sind bereits 25 aktive API-Schlüssel vorhanden.
key_daily_limit	400	Es wurden heute bereits 10 API-Schlüssel angelegt.
weekly_send_limit	403	Das wöchentliche Versandkontingent ist erreicht. Details enthält limit, used und plan.
invalid_unread_only	400	unread_only ist nicht true oder false.
invalid_notification_id	400	Die Kennung einer Benachrichtigung ist ungültig.

Fehler behandeln

Bei 400 die Anfrage anhand von code, message und details korrigieren. Nicht automatisch wiederholen.
Bei 401 den Schlüssel prüfen. Ein zurückgezogener Schlüssel wird nie wieder gültig.
Bei 403 den Plan und die Rolle prüfen. Ein Planwechsel hilft sofort.
Bei 404 die Kennung prüfen. Die Ressource kann gelöscht worden sein.
Bei 409 den Zustand prüfen. idempotency_conflict bedeutet einen anderen Rumpf beim selben Schlüssel, event_has_registrations ein veröffentlichtes Event mit Anmeldungen.
Bei 429 den Wert von Retry-After abwarten.
Bei 500 und 503 mit wachsender Pause erneut versuchen.

POST /events akzeptiert einen Idempotency-Key. Gleicher Schlüssel und gleicher Rumpf liefern dieselbe Antwort, ein anderer Rumpf ergibt 409 idempotency_conflict. Ohne Schlüssel legt ein wiederholter POST ein neues Event an.