Error & batas laju

Bentuk error

Setiap respons non-2xx berupa JSON dengan bentuk:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the `generation:run` scope.",
    "required_scope": "generation:run",
    "granted_scopes": ["books:read"]
  }
}

Kode umum

HTTP	`error.code`	Arti
400	`invalid_request`	Body atau query gagal validasi skema.
400	`invalid_state`	Buku/bab ada tetapi tidak dalam keadaan yang mendukung tindakan tersebut (mis. menerbitkan buku dengan bab kosong).
400	`unreadable`	File tidak bisa diurai atau tidak punya teks yang bisa dipakai (mis. PDF hasil pindai).
401	`unauthenticated`	Header Authorization tidak ada atau formatnya salah.
401	`invalid_token`	Token tidak dikenal, kedaluwarsa, atau sudah dicabut.
403	`insufficient_scope`	Token valid tetapi tidak memiliki cakupan yang dibutuhkan endpoint — buat kunci baru dengan cakupan yang tercantum.
404	`not_found`	Buku atau bab tidak ada (atau bukan milik Anda).
413	`payload_too_large`	File atau isi permintaan terlalu besar. Untuk naskah, batas ini juga berlaku pada teks hasil ekstraksi, yang bisa melampauinya pada file EPUB atau Word terkompresi.
502	`generation_failed`, `narration_failed`	Penyedia hilir (Anthropic, ElevenLabs) gagal. Aman untuk dicoba ulang.
503	`feature_disabled`	Instans Anthra belum mengonfigurasi kunci hulu yang dibutuhkan (mis. ELEVENLABS_API_KEY untuk narasi).

Batas laju

Anthra menerapkan kuota per akun untuk operasi yang mahal (pembuatan bab, narasi). Saat mencapai batas, Anda akan menerima HTTP 429 dengan retry-after berisi jumlah detik untuk menunggu. Body 429 memakai bentuk error yang sama.

Tugas pembuatan juga dibatasi oleh maxDuration = 300s di Vercel Functions — penulisan bab yang memang butuh waktu lebih lama harus dikirim ulang (konten parsial sudah tersimpan sebelum batas waktu).

Idempotensi

Endpoint yang mengubah data saat ini tidak idempoten. Gunakan kunci unik per permintaan (mis. POST /v1/books selalu membuat buku baru). Jika Anda butuh semantik paling-banyak-sekali, lakukan deduplikasi di sisi klien sebelum mencoba ulang.