Kesalahan

Dapatkan kunci API

Setiap kesalahan dijawab dengan status HTTP dan amplop JSON yang sama. code adalah kontrak yang dibaca kode Anda; message ditulis untuk manusia dan dapat berubah.

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 memberi lebih banyak informasi: field yang ditolak, alasan sebuah jaringan, jendela batas laju yang habis.
docUrl mengarah ke penjelasan kode di halaman ini.
requestId mengidentifikasi permintaan: berikan ke tim dukungan.

Endpoint OAuth (/v1/oauth/token, /v1/oauth/authorize) menjawab dengan format RFC 6749: { "error": "invalid_grant", "error_description": "…" }.

Kode kesalahan

Status	Kode	Arti
400	`invalid_request`	Body, query, atau parameter tidak valid. Satu rincian per field yang ditolak: `field`, `code` (`required`, `is_string`, `max`…), dan `message`.
400	`invalid_json`	Body bukan JSON yang valid.
400	`invalid_cursor`	Kursor tidak dikembalikan oleh Sofia API.
400	`webhook_url_invalid`	Alamat webhook bukan https, atau mengarah ke alamat privat.
400	`webhook_event_invalid`	Event webhook tidak dikenal.
400	`application_name_invalid`	Pengaturan › API: nama klien tidak ada atau terlalu panjang.
400	`application_profile_invalid`	Pengaturan › API: ada kolom profil klien yang tidak valid; rinciannya menyebutkannya.
400	`logo_invalid`	Pengaturan › API: logo ditolak (minimal 180×180 px, PNG, JPEG, atau WebP, maksimal 2 MB).
401	`invalid_token`	Token tidak ada, tidak dikenal, kedaluwarsa, atau dicabut, atau orang di baliknya kehilangan hak yang dibawanya. Lihat header `WWW-Authenticate`.
401	`unauthorized`	Autentikasi diperlukan.
402	`subscription_required`	Penulisan live (termasuk dry run) memerlukan langganan aktif atau masa percobaan.
403	`insufficient_scope`	Token tidak memiliki scope endpoint; rinciannya menyebutkannya.
403	`insufficient_role`	Peran Anda di Workspace ini tidak mengizinkan tindakan ini.
403	`live_mode_required`	Penulisan nyata dengan token uji.
403	`route_closed_to_applications`	Endpoint ini tidak terbuka untuk aplikasi.
403	`forbidden`	Akses ditolak.
403	`session_required`	Pengaturan › API: tindakan ini memerlukan sesi Sofia, bukan token.
403	`impersonation_forbidden`	Pengaturan › API: tindakan ini ditolak dalam sesi pinjaman.
403	`workspace_owner_required`	Hanya pemilik Workspace yang dapat melakukannya.
403	`workspace_member_required`	Anda bukan anggota Workspace ini.
404	`route_not_found`	Tidak ada endpoint yang menjawab metode dan path ini.
404	`establishment_not_found`	Usaha tidak dikenal, atau di luar jangkauan token.
404	`media_not_found`	Media tidak dikenal, atau di luar jangkauan token.
404	`post_not_found`	Postingan tidak dikenal, atau di luar jangkauan token.
404	`webhook_not_found`	Webhook tidak dikenal, atau milik aplikasi lain.
404	`not_found`	Sumber daya tidak ada.
404	`application_not_found`	Pengaturan › API: klien tidak dikenal.
404	`grant_not_found`	Otorisasi tidak dikenal, atau sudah dicabut.
404	`personal_key_not_found`	Pengaturan › API: kunci pribadi tidak dikenal.
404	`consent_not_found`	Permintaan otorisasi sudah kedaluwarsa atau tidak ada: mulai lagi dari endpoint otorisasi.
405	`method_not_allowed`	Metode ini tidak diizinkan pada endpoint ini.
409	`post_in_flight`	Sebuah jaringan sedang mengirim postingan: coba hapus lagi sebentar lagi.
409	`post_not_editable`	Sebuah jaringan sudah mengirim postingan: tidak dapat diedit lagi.
409	`account_already_connected`	Jaringan ini sudah terhubung ke usaha.
409	`webhook_limit_reached`	Aplikasi sudah memiliki 10 webhook.
409	`idempotency_in_progress`	Permintaan pertama dengan `Idempotency-Key` ini masih berjalan.
409	`conflict`	Permintaan bertentangan dengan keadaan sumber daya saat ini.
409	`scope_removal_forbidden`	Pengaturan › API: izin klien dapat ditambahkan tetapi tidak dapat dihapus.
409	`public_client_has_no_secret`	Pengaturan › API: klien publik tidak memiliki secret.
413	`payload_too_large`	File melebihi batas unggah.
415	`unsupported_media_type`	Tipe konten tidak didukung.
422	`post_refused`	Sebuah jaringan, usaha, atau paket Anda akan menolak postingan. Satu rincian per alasan, masing-masing dengan `message`-nya.
422	`media_import_refused`	Media tidak dapat diimpor dari URL ini; rinciannya menyebut alasannya.
422	`media_upload_refused`	File yang diunggah bukan gambar atau video yang didukung.
422	`platform_not_offered`	Jaringan ini tidak ditawarkan untuk dihubungkan.
422	`idempotency_key_reused`	`Idempotency-Key` ini dipakai dengan body yang berbeda.
422	`unprocessable_entity`	Permintaan dipahami tetapi tidak dapat diproses.
429	`rate_limit_exceeded`	Jendela batas laju penuh: tunggu sesuai `Retry-After`.

Alasan postingan ditolak

post_refused mencantumkan setiap alasan di details[].code:

Kode	Arti
`unsupported_platform`	Jaringan ini tidak didukung.
`duplicate_platform`	Jaringan yang sama disebut dua kali.
`unsupported_format`	Jaringan ini tidak menawarkan format ini.
`caption_too_long`	Teks terlalu panjang (`max`, `actual`).
`too_many_hashtags`	Terlalu banyak hashtag (`max`, `actual`).
`too_many_mentions`	Terlalu banyak mention (`max`, `actual`).
`too_many_thread_posts`	Thread terlalu panjang (`max`, `actual`).
`too_many_media`	Terlalu banyak media (`max`, `actual`).
`media_mix_refused`	Foto dan video tidak dapat dicampur di jaringan ini.
`media_required`	Jaringan ini memerlukan foto atau video.
`media_type_refused`	Jaringan ini tidak menerima jenis media ini.
`scheduled_in_past`	`scheduledAt` sudah lewat.
`scheduled_at_invalid`	Postingan terjadwal memerlukan `scheduledAt` di masa depan.
`account_not_connected`	Tidak ada akun yang terhubung di jaringan ini untuk usaha ini.
`account_ambiguous`	Beberapa akun terhubung di jaringan ini: sebutkan satu dengan `accountId`.
`media_not_found`	Media tidak ada di pustaka usaha ini.
`media_url_invalid`	URL media harus berupa alamat https publik.
`platform_unavailable`	Jaringan ini belum dibuka di Sofia.
`publication_quota_exceeded`	Kuota publikasi paket Anda telah tercapai.

Menangani kesalahan

Bercabanglah berdasarkan code, jangan pernah message.
Coba ulang 429 setelah Retry-After, dan 5xx dengan exponential backoff.
Jangan pernah mencoba ulang 4xx tanpa perubahan: perbaiki permintaan terlebih dahulu.
Catat requestId pada setiap kegagalan.