Error

Format envelope error Hostlinku, daftar kode error, dan cara menanganinya

Semua error dari gateway Hostlinku memakai satu bentuk envelope yang sama, apa pun sumbernya — validasi, autentikasi, billing, maupun kegagalan provider upstream:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request body tidak valid.",
    "details": {
      "issues": [{ "path": "messages", "message": "Array must contain at least 1 element(s)" }]
    }
  }
}

• status — selalu "error" pada respons gagal.
• error.code — kode mesin (stabil, aman untuk percabangan logika di kode Anda).
• error.message — pesan manusia, bisa berbahasa Indonesia.
• error.details — opsional; mis. detail per-field saat validasi gagal.

Daftar kode error

Detail validasi (422)

Saat validasi gagal, details.issues memuat daftar masalah per field:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request body tidak valid.",
    "details": {
      "issues": [
        { "path": "messages", "message": "Array must contain at least 1 element(s)" },
        { "path": "temperature", "message": "Number must be less than or equal to 2" }
      ]
    }
  }
}

Error pada streaming

Kegagalan yang terjadi di tengah stream SSE dikirim sebagai event data di stream yang sama (bukan sebagai HTTP status):

data: {"error":{"code":"UPSTREAM_ERROR","message":"Upstream error.","type":"upstream_error"}}

Gateway tidak akan mengirim data: [DONE] setelah event error — stream yang terputus selalu bisa dibedakan dari stream yang selesai normal.

Menangani error di kode

Divisi penanganan yang disarankan:

• 401 → kunci salah/kedaluwarsa: perbaiki konfigurasi; jangan retry berulang.
• 402 → top-up saldo atau naikkan/atur ulang limit kunci; lihat Billing & Saldo.
• 422 → perbaiki body request; baca details.issues untuk lokasi masalah.
• 429 → backoff eksponensial + hormati header rate limit; lihat Pemakaian & Limit.
• 5xx (UPSTREAM_ERROR, PROVIDER_UNAVAILABLE, INTERNAL) → retry dengan backoff beberapa kali; gateway sudah mencoba failover antar gateway sebelum menyerah.

Contoh menangkap error dengan SDK OpenAI (Python):

import openai
from openai import OpenAI

client = OpenAI(base_url="https://api.hostlinku.com/v1", api_key="sk-isi-kunci-anda")

try:
    response = client.chat.completions.create(
        model="gpt-5-4-mini",
        messages=[{"role": "user", "content": "Halo"}],
    )
except openai.AuthenticationError as err:      # 401
    raise SystemExit(f"Kunci API bermasalah: {err}")
except openai.RateLimitError as err:           # 429
    raise SystemExit(f"Rate limit: {err}")
except openai.APIStatusError as err:           # 4xx/5xx lainnya
    print("status:", err.status_code, "body:", err.response.text)