Fehler

API-Schlüssel erhalten

Jeder Fehler antwortet mit einem HTTP-Status und demselben JSON-Envelope. code ist der Vertrag, den Ihr Code liest; message ist für Menschen geschrieben und kann sich ändern.

json

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid",
    "details": [
      { "field": "targets[0].text", "code": "required", "message": "targets[0].text is required" }
    ],
    "docUrl": "https://www.sofia-post.com/developers/errors#invalid_request",
    "requestId": "2aab5943-6333-4caf-8478-25a85ebd4abf"
  }
}

details sagt mehr: das abgelehnte Feld, den Grund eines Netzwerks, das erschöpfte Rate-Limit-Fenster.
docUrl führt zur Erklärung des Codes auf dieser Seite.
requestId identifiziert die Anfrage: Geben Sie sie dem Support an.

Die OAuth-Endpoints (/v1/oauth/token, /v1/oauth/authorize) antworten im Format von RFC 6749: { "error": "invalid_grant", "error_description": "…" }.

Fehlercodes

Status	Code	Bedeutung
400	`invalid_request`	Der Body, die Query oder ein Parameter ist ungültig. Ein Detail pro abgelehntem Feld: `field`, `code` (`required`, `is_string`, `max` …) und `message`.
400	`invalid_json`	Der Body ist kein gültiges JSON.
400	`invalid_cursor`	Der Cursor wurde nicht von Sofia API zurückgegeben.
400	`webhook_url_invalid`	Die Webhook-Adresse ist nicht https oder führt zu einer privaten Adresse.
400	`webhook_event_invalid`	Unbekanntes Webhook-Event.
400	`application_name_invalid`	Einstellungen › API: Der Name des Clients fehlt oder ist zu lang.
400	`application_profile_invalid`	Einstellungen › API: Ein Feld des Client-Profils ist ungültig; das Detail nennt es.
400	`logo_invalid`	Einstellungen › API: Das Logo wird abgelehnt (mindestens 180×180 px, PNG, JPEG oder WebP, höchstens 2 MB).
401	`invalid_token`	Das Token fehlt, ist unbekannt, abgelaufen oder widerrufen, oder die Person dahinter hat die Rechte verloren, die es trägt. Siehe den Header `WWW-Authenticate`.
401	`unauthorized`	Authentifizierung erforderlich.
402	`subscription_required`	Ein echter Schreibzugriff (Probelauf eingeschlossen) erfordert ein aktives Abonnement oder eine Testphase.
403	`insufficient_scope`	Dem Token fehlt der Scope des Endpoints; das Detail nennt ihn.
403	`insufficient_role`	Ihre Rolle in diesem Workspace erlaubt diese Aktion nicht.
403	`live_mode_required`	Ein echter Schreibzugriff mit einem Test-Token.
403	`route_closed_to_applications`	Dieser Endpoint steht Anwendungen nicht offen.
403	`forbidden`	Zugriff verweigert.
403	`session_required`	Einstellungen › API: Diese Aktion braucht eine Sofia-Sitzung, kein Token.
403	`impersonation_forbidden`	Einstellungen › API: Diese Aktion wird in einer geliehenen Sitzung abgelehnt.
403	`workspace_owner_required`	Nur der Eigentümer des Workspace kann das tun.
403	`workspace_member_required`	Sie sind kein Mitglied dieses Workspace.
404	`route_not_found`	Kein Endpoint antwortet auf diese Methode und diesen Pfad.
404	`establishment_not_found`	Unbekannter Betrieb oder außerhalb der Reichweite des Tokens.
404	`media_not_found`	Unbekanntes Medium oder außerhalb der Reichweite des Tokens.
404	`post_not_found`	Unbekannter Beitrag oder außerhalb der Reichweite des Tokens.
404	`webhook_not_found`	Unbekannter Webhook oder der einer anderen Anwendung.
404	`not_found`	Die Ressource existiert nicht.
404	`application_not_found`	Einstellungen › API: Unbekannter Client.
404	`grant_not_found`	Unbekannte oder bereits widerrufene Autorisierung.
404	`personal_key_not_found`	Einstellungen › API: Unbekannter persönlicher Schlüssel.
404	`consent_not_found`	Die Autorisierungsanfrage ist abgelaufen oder existiert nicht: Beginnen Sie erneut beim Autorisierungs-Endpunkt.
405	`method_not_allowed`	Diese Methode ist auf diesem Endpunkt nicht erlaubt.
409	`post_in_flight`	Ein Netzwerk sendet den Beitrag gerade: Versuchen Sie das Löschen einen Moment später erneut.
409	`post_not_editable`	Ein Netzwerk hat den Beitrag bereits gesendet: Er kann nicht mehr bearbeitet werden.
409	`account_already_connected`	Dieses Netzwerk ist bereits mit dem Betrieb verbunden.
409	`webhook_limit_reached`	Die Anwendung hat bereits 10 Webhooks.
409	`idempotency_in_progress`	Die erste Anfrage mit diesem `Idempotency-Key` läuft noch.
409	`conflict`	Die Anfrage steht im Widerspruch zum aktuellen Zustand der Ressource.
409	`scope_removal_forbidden`	Einstellungen › API: Eine Berechtigung eines Clients kann hinzugefügt, aber nicht entfernt werden.
409	`public_client_has_no_secret`	Einstellungen › API: Ein öffentlicher Client hat kein Secret.
413	`payload_too_large`	Die Datei überschreitet das Upload-Limit.
415	`unsupported_media_type`	Nicht unterstützter Content-Type.
422	`post_refused`	Ein Netzwerk, der Betrieb oder Ihr Tarif würde den Beitrag ablehnen. Ein Detail pro Grund, jeweils mit seiner `message`.
422	`media_import_refused`	Das Medium konnte nicht von dieser URL importiert werden; das Detail nennt den Grund.
422	`media_upload_refused`	Die hochgeladene Datei ist kein unterstütztes Bild oder Video.
422	`platform_not_offered`	Dieses Netzwerk wird nicht zur Verbindung angeboten.
422	`idempotency_key_reused`	Dieser `Idempotency-Key` wurde mit einem anderen Body verwendet.
422	`unprocessable_entity`	Die Anfrage wird verstanden, kann aber nicht verarbeitet werden.
429	`rate_limit_exceeded`	Ein Rate-Limit-Fenster ist voll: Warten Sie `Retry-After` ab.

Gründe für einen abgelehnten Beitrag

Ein post_refused listet jeden Grund in details[].code auf:

Code	Bedeutung
`unsupported_platform`	Dieses Netzwerk wird nicht unterstützt.
`duplicate_platform`	Dasselbe Netzwerk wird zweimal genannt.
`unsupported_format`	Dieses Netzwerk bietet dieses Format nicht an.
`caption_too_long`	Der Text ist zu lang (`max`, `actual`).
`too_many_hashtags`	Zu viele Hashtags (`max`, `actual`).
`too_many_mentions`	Zu viele Erwähnungen (`max`, `actual`).
`too_many_thread_posts`	Der Thread ist zu lang (`max`, `actual`).
`too_many_media`	Zu viele Medien (`max`, `actual`).
`media_mix_refused`	Fotos und Videos lassen sich in diesem Netzwerk nicht mischen.
`media_required`	Dieses Netzwerk braucht ein Foto oder ein Video.
`media_type_refused`	Dieses Netzwerk akzeptiert diesen Medientyp nicht.
`scheduled_in_past`	`scheduledAt` liegt in der Vergangenheit.
`scheduled_at_invalid`	Ein geplanter Beitrag braucht ein zukünftiges `scheduledAt`.
`account_not_connected`	Für diesen Betrieb ist in diesem Netzwerk kein Konto verbunden.
`account_ambiguous`	In diesem Netzwerk sind mehrere Konten verbunden: Geben Sie eines mit `accountId` an.
`media_not_found`	Das Medium befindet sich nicht in der Mediathek dieses Betriebs.
`media_url_invalid`	Die Medien-URL muss eine öffentliche https-Adresse sein.
`platform_unavailable`	Dieses Netzwerk ist bei Sofia noch nicht freigeschaltet.
`publication_quota_exceeded`	Das Veröffentlichungskontingent Ihres Tarifs ist erreicht.

Fehler behandeln

Verzweigen Sie anhand von code, nie anhand von message.
Wiederholen Sie 429 nach Retry-After und 5xx mit exponentiellem Backoff.
Wiederholen Sie ein 4xx nie unverändert: Korrigieren Sie zuerst die Anfrage.
Protokollieren Sie requestId bei jedem Fehler.