Utviklerdokumentasjon
Feilsøk API-, CLI- og MCP-tilkoblinger
Løs feil med innlogging, tillatelser, skjema, opplasting og usikre skriveoperasjoner uten å eksponere legitimasjon eller duplisere akseptert arbeid.
Les som MarkdownGjennomgått av SosoAPI-teamet ·
Feil nettleser eller blokkert lokal innlogging
Stopp ventende innlogging og kjør auth login --no-open. Åpne den nye utskrevne URL-en i nettleserprofilen du vil bruke. Kontroller konto og arbeidsområde før du gir tilgang, og bruk bare én nettleserprofil for innloggingslenken. Hvis port 8789 er opptatt, identifiser prosessen som lytter, og stopp den bare hvis det er en innloggingsprosess du startet.
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401, 403 og utilgjengelige kontoer
Ved 401, kontroller at du er innlogget med gyldig legitimasjon. Ved 403, kontroller arbeidsområderollen, valgt omfang og funksjonen operasjonen krever. Bruk auth status og verifiser kontoens e-post og godtatt legitimasjonstype. Endre tilgang bare hvis operasjonen trenger det; bytte av verktøyprofil gir ikke tillatelse.
Kontroller den sosiale kontoen separat. Les tilkobling og funksjoner, og koble bare til igjen hvis leverandøren trenger fornyet samtykke. En intern tjenestefeil er ingen grunn til å gjenopprette en fungerende tilkobling.
400-validering og versjonsavvik
Les svarinnhold og baner til valideringsfelter. Valideringsfeil kan inneholde en ZodError; håndteringsfeil kan bruke feltene error, message og code. Sammenlign forespørselen med installert kontrakt og oppdater klientpakken ved behov. Rett feltene nevnt i feilen uten å fjerne påkrevde verdier eller legge til ustøttede filtre.
npx sosoapi api contract --route /studio-api/scheduled-posts/409, 429, 5xx eller en skriveoperasjon med tidsavbrudd
Ved 409, les siste ressursversjon og tilgjengelige handlinger før endring. Ved 429, vent i henhold til Retry-After og reduser samtidighet. Hvis en skriveoperasjon får tidsavbrudd eller returnerer 5xx, behold ID-en og kontroller eksisterende resultat først: serveren kan ha akseptert den før tilkoblingen sviktet.
Prøv bare igjen når operasjonen og gjeldende tilstand tillater det. Behold samme nøkkel for samme nyttelast, og ikke opprett en erstatning for å omgå et usikkert resultat. Rett autentiseringsfeil før nye forsøk. Hvis en bakgrunnsjobb fortsatt venter, kan statusen allerede inneholde en kjøringsfeil som er verdt å kontrollere.
Opplastings- eller verktøyoppdagelsesproblemer
Lokal opplasting godtar støttede mediefiler på opptil 500 MiB fra arbeidsmappen, den midlertidige mappen, Pictures/Movies/Videos eller mapper i SOSOAPI_UPLOAD_ROOTS. Punktmapper og symbolske lenker som går utenfor disse røttene, avvises. Legg til den spesifikke mediemappen du trenger fremfor hele hjemmemappen. En HTTP-tilkobling kan ikke lese lokale filer.
Hvis verktøy mangler, koble til klienten igjen og sammenlign profil og tilkoblingstype med referansen. Kontroller at verktøyene er lastet i gjeldende samtale; et lagret servernavn alene bekrefter ikke dette.
Del nyttig diagnostikk trygt
Del operasjonsnavn, tidspunkt, HTTP-status, trygg feilkode og request_id eller x-request-id hvis tilgjengelig. Ta med CLI-versjon og om du brukte lokal eller ekstern MCP. Fjern tokener, informasjonskapsler, autorisasjonslenker, signerte medie-URL-er, kundeinnhold og private ID-er. Del relevant feil fremfor en legitimasjonsfil eller et helt svar.