Dokumentasi pengembang
Atasi masalah koneksi API, CLI, dan MCP
Atasi kegagalan masuk, izin, skema, unggahan, dan penulisan belum pasti tanpa mengekspos kredensial atau menduplikasi pekerjaan yang diterima.
Baca sebagai MarkdownDitinjau tim SosoAPI ·
Browser salah atau login lokal terblokir
Hentikan proses masuk tertunda, lalu jalankan auth login --no-open. Buka URL baru yang dicetak pada profil browser yang ingin digunakan. Periksa akun dan ruang kerja sebelum memberikan akses, dan gunakan hanya satu profil browser untuk tautan masuk tersebut. Jika port 8789 terpakai, identifikasi listener dan hentikan hanya jika itu proses masuk yang Anda mulai.
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401, 403, dan akun tidak tersedia
Untuk 401, periksa bahwa Anda masuk dengan kredensial terkini. Untuk 403, periksa peran ruang kerja, cakupan terpilih, dan kemampuan yang diperlukan operasi. Gunakan auth status dan verifikasi email akun serta jenis kredensial yang diterima. Ubah akses hanya jika diperlukan operasi tersebut; mengganti profil alat tidak akan memberikan izin.
Periksa akun sosial secara terpisah. Baca koneksi dan kemampuannya, serta hubungkan ulang hanya jika penyedia memerlukan persetujuan baru. Kesalahan layanan internal bukan alasan membuat ulang koneksi yang sehat.
Validasi 400 dan perbedaan versi
Baca isi respons dan path kolom validasi. Kesalahan validasi mungkin berisi ZodError; kesalahan handler mungkin menggunakan kolom error, message, dan code. Bandingkan permintaan dengan kontrak terpasang dan perbarui paket klien jika perlu. Perbaiki kolom yang disebutkan dalam kesalahan tanpa menghapus nilai wajib atau menambahkan filter yang tidak didukung.
npx sosoapi api contract --route /studio-api/scheduled-posts/409, 429, 5xx, atau penulisan yang timeout
Untuk 409, baca versi sumber daya terbaru dan tindakan tersedia sebelum mengubahnya. Untuk 429, tunggu sesuai Retry-After dan kurangi konkurensi. Jika penulisan timeout atau mengembalikan 5xx, simpan ID dan periksa hasil yang ada terlebih dahulu: server mungkin sudah menerimanya sebelum koneksi gagal.
Coba lagi hanya jika operasi dan status terkininya mengizinkan. Pertahankan kunci sama untuk payload sama, dan jangan buat pengganti untuk melewati hasil belum pasti. Perbaiki kegagalan autentikasi sebelum mencoba lagi. Jika tugas latar belakang masih tertunda, statusnya mungkin sudah berisi kesalahan eksekusi yang perlu diperiksa.
Masalah unggahan atau penemuan alat
Unggahan lokal menerima file media didukung hingga 500 MiB dari direktori kerja, folder sementara, Pictures/Movies/Videos, atau folder dalam SOSOAPI_UPLOAD_ROOTS. Folder berawalan titik dan symlink yang keluar dari direktori tersebut ditolak. Tambahkan folder media tertentu yang diperlukan, bukan seluruh direktori home. Koneksi HTTP tidak dapat membaca file lokal.
Jika alat hilang, hubungkan ulang klien dan bandingkan profil serta jenis koneksinya dengan referensi. Periksa apakah alat dimuat dalam percakapan saat ini; nama server tersimpan saja tidak mengonfirmasinya.
Bagikan diagnostik bermanfaat dengan aman
Bagikan nama operasi, waktu, status HTTP, kode kesalahan aman, serta request_id atau x-request-id jika tersedia. Sertakan versi CLI dan apakah menggunakan MCP lokal atau jarak jauh. Hapus token, cookie, tautan otorisasi, URL media bertanda tangan, konten pelanggan, dan ID pribadi. Bagikan kesalahan relevan, bukan file kredensial atau seluruh respons.