Errors

Error format

{
  "error": {
    "type": "error_type",
    "message": "Deskripsi error"
  }
}

Common errors (v2 & v3 sama)

Status	Type	Penyebab	Solusi
401	authentication_error	API key invalid / expired / header salah	cek Authorization: Bearer sk-xxx atau x-api-key
403	forbidden	Model butuh plan aktif	upgrade plan
403	model_not_allowed	Model tidak termasuk allowed_models plan	cek GET /v3/models, lihat Settings
403	model_not_available	Plan free tidak dapat akses sonnet4.6	fallback bt/sonnet4.5 atau upgrade
404	model_not_found	Slug tidak ada di katalog	cek GET /v3/models
429	rate_limit_exceeded	Per-user RPM terlampaui	tunggu & retry dengan backoff
429	monthly_limit_exceeded	Pool bulanan habis	tunggu bulan depan / top-up
429	daily_model_limit_exceeded	Kuota per-model harian habis	ganti model / tunggu besok
429	batch_too_large	>50 sub-request per /batch	pecah batch
503	server_busy	Semaphore penuh (MAX_CONCURRENT)	retry 1–3s
503	upstream_error / no_providers	Semua provider gagal	coba ulang, ganti v2↔v3, atau fallback sonnet4.5
503	upstream_capacity	Semua provider kehabisan kuota	sama — cek header x-fallback-model
400	invalid_request	JSON invalid / body >10MB / duplikat tool_use	cek payload, pastikan tool_use_id unik

x-fallback-model: bt/sonnet4.5 berarti request sonnet4.6 yang diminta dialihkan — usage dicatat atas fallback (billing jujur). Daftar lengkap + opencode.json settings: Settings API.