Penanganan Error

Panduan ini memperkenalkan format respons kesalahan 诺玛AI, skenario kesalahan umum, dan strategi penanganan yang direkomendasikan.

Format Respons Kesalahan#

Semua respons kesalahan mengikuti format JSON yang seragam:

{
  "error": {
    "code": "invalid_api_key",
    "message": "API Key yang diberikan tidak valid, silakan periksa dan coba lagi.",
    "type": "authentication_error"
  }
}

HTTP Kode Status#

Kode Status

Tipe

Deskripsi

Perlu Dicoba Ulang

`400`

`invalid_request_error`

Parameter permintaan tidak valid

❌ Perbaiki parameter lalu coba ulang

`401`

`authentication_error`

API Key tidak valid atau tidak ada

❌ Periksa API Key

`403`

`permission_error`

Izin tidak mencukupi

❌ Periksa izin akun

`404`

`not_found_error`

Model atau sumber daya tidak ditemukan

❌ Periksa ID model

`429`

`rate_limit_error`

Batas kecepatan terlampaui

✅ Tunggu lalu coba ulang

`500`

`internal_error`

Kesalahan server internal

✅ Coba lagi nanti

`502`

`upstream_error`

Kesalahan penyedia model hulu

✅ Ganti model atau coba ulang

`503`

`service_unavailable`

Layanan sementara tidak tersedia

✅ Coba lagi nanti

Kesalahan Umum dan Solusi#

401 — API Key Tidak Valid

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Solusi:

• Periksa apakah API Key disalin dengan benar (termasuk awalan `sk-`)
• Pastikan Key belum kedaluwarsa atau dinonaktifkan
• Periksa apakah variabel lingkungan dimuat dengan benar

429 — Batas Kecepatan

Solusi:

• Periksa `x-ratelimit-reset-requests` di header respons
• Implementasikan percobaan ulang dengan backoff eksponensial
• Jika butuh kuota lebih tinggi, hubungi dukungan untuk penyesuaian

502 — Kesalahan Hulu

Solusi:

• Gunakan Fallback untuk beralih otomatis ke model cadangan
• Coba lagi nanti
• Periksa halaman status penyedia model

Strategi Percobaan Ulang#

Direkomendasikan menggunakan strategi **Exponential Backoff (Mundur Eksponensial)**:

import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<APINOMA_API_KEY Anda>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """Pembungkus percobaan ulang dengan backoff eksponensial"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: tunggu lalu coba ulang
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Batas kecepatan terlampaui, menunggu {wait:.1f}s sebelum mencoba ulang...")
            time.sleep(wait)
 
        except APIConnectionError:
            # Kesalahan jaringan: tunggu sebentar lalu coba ulang
            wait = 2 ** attempt
            print(f"Kesalahan koneksi, menunggu {wait}s sebelum mencoba ulang...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: kesalahan server, coba ulang
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: kesalahan klien, jangan coba ulang
                raise
 
    raise Exception(f"Gagal setelah {max_retries} kali percobaan ulang")
 
# Penggunaan
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Halo"}]
)

Pengaturan Timeout#

Disarankan untuk menetapkan waktu timeout yang wajar untuk panggilan API:

# Python OpenAI SDK
client = OpenAI(
    base_url="https://as.apinoma.com/v1",
    api_key="<APINOMA_API_KEY Anda>",
    timeout=60.0,  # timeout 60 detik
    max_retries=3  # percobaan ulang bawaan SDK
)

Permintaan streaming disarankan menggunakan waktu timeout yang lebih lama (120-300 detik), karena model mungkin membutuhkan waktu lebih lama untuk menghasilkan konten lengkap.

Praktik Terbaik#

• Bedakan kesalahan yang dapat dicoba ulang dan yang tidak — 4xx biasanya perlu modifikasi permintaan, 5xx dapat dicoba ulang
• Gunakan backoff eksponensial — hindari percobaan ulang yang sering saat ada pembatasan kecepatan
• Tetapkan jumlah percobaan ulang maksimum — cegah percobaan ulang tanpa batas
• Catat log kesalahan — memudahkan pemecahan masalah
• Konfigurasikan Fallback — gunakan parameter `provider.fallback` 诺玛AI untuk beralih model secara otomatis
• Pantau tingkat kesalahan — perhatikan tren kesalahan di Konsol

Terakhir diperbarui pada 23 Juni 2026