Entwicklerdokumentation
API-, CLI- und MCP-Verbindungen diagnostizieren
Behebe Anmelde-, Berechtigungs-, Schema-, Upload- und ungewisse Schreibfehler, ohne Zugangsdaten offenzulegen oder angenommene Arbeit zu duplizieren.
Als Markdown lesenVom SosoAPI-Team geprüft ·
Falscher Browser oder blockierte lokale Anmeldung
Stoppe die ausstehende Anmeldung und führe auth login --no-open aus. Öffne die neu ausgegebene URL im gewünschten Browserprofil. Prüfe Konto und Workspace vor der Zugriffserteilung und nutze nur ein Browserprofil für diesen Link. Ist Port 8789 belegt, ermittle den Listener und stoppe ihn nur, wenn es ein von dir gestarteter Anmeldeprozess ist.
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401, 403 und nicht verfügbare Konten
Prüfe bei 401 die Anmeldung mit aktuellen Zugangsdaten. Prüfe bei 403 Workspace-Rolle, gewählten Umfang und benötigte Funktion. Nutze auth status und verifiziere Konto-E-Mail sowie akzeptierten Zugangsdaten-Typ. Ändere Zugriff nur bei Bedarf der Operation; ein Profilwechsel erteilt keine Berechtigung.
Prüfe das Social-Media-Konto separat. Lies Verbindung und Funktionen und verbinde nur bei nötiger neuer Anbieterzustimmung neu. Interne Dienstfehler rechtfertigen keine Neuerstellung gesunder Verbindungen.
400-Validierung und Versionsabweichung
Lies Antwortinhalt und Validierungsfeldpfade. Validierungsfehler können ZodError enthalten, Handler-Fehler error, message und code. Vergleiche Anfrage und installierten Vertrag und aktualisiere bei Bedarf das Client-Paket. Behebe genannte Felder, ohne Pflichtwerte zu entfernen oder nicht unterstützte Filter zu ergänzen.
npx sosoapi api contract --route /studio-api/scheduled-posts/409, 429, 5xx oder ein Schreibvorgang mit Timeout
Lies bei 409 die neueste Ressourcenversion und verfügbare Aktionen vor Änderungen. Warte bei 429 gemäß Retry-After und verringere Parallelität. Bei Schreib-Timeout oder 5xx behalte die ID und prüfe zuerst das bestehende Ergebnis: Der Server könnte vor dem Verbindungsfehler angenommen haben.
Wiederhole nur, wenn Operation und aktueller Zustand es erlauben. Behalte denselben Schlüssel für denselben Payload und erstelle keinen Ersatz zur Umgehung ungewisser Ergebnisse. Behebe Authentifizierungsfehler zuerst. Ein ausstehender Hintergrundjob kann bereits einen relevanten Ausführungsfehler im Status enthalten.
Upload- oder Tool-Erkennungsprobleme
Lokaler Upload akzeptiert unterstützte Medien bis 500 MiB aus Arbeitsverzeichnis, temporärem Ordner, Pictures/Movies/Videos oder SOSOAPI_UPLOAD_ROOTS-Ordnern. Punktordner und aus diesen Wurzeln führende Symlinks werden abgelehnt. Ergänze gezielt benötigte Medienordner statt des gesamten Home-Verzeichnisses. Eine HTTP-Verbindung kann lokale Dateien nicht lesen.
Fehlen Tools, verbinde den Client neu und vergleiche Profil und Verbindungstyp mit der Referenz. Prüfe geladene Tools im aktuellen Gespräch; ein gespeicherter Servername allein bestätigt dies nicht.
Hilfreiche Diagnosedaten sicher teilen
Teile Operationsname, Zeitpunkt, HTTP-Status, sicheren Fehlercode und verfügbare request_id oder x-request-id. Nenne CLI-Version und lokales oder Remote-MCP. Entferne Token, Cookies, Autorisierungslinks, signierte Medien-URLs, Kundeninhalte und private IDs. Teile den relevanten Fehler statt einer Zugangsdaten-Datei oder kompletten Antwort.