Langsung ke konten utama

Format Respon Kesalahan

Semua kesalahan mengembalikan format JSON yang konsisten dengan opsi petunjuk Agent-First:
{
  "error": {
    "message": "Human-readable error description",
    "type": "error_type",
    "code": "error_code",
    "param": "parameter_name",
    "did_you_mean": "suggested_model",
    "suggestions": [{"id": "model-id"}],
    "hint": "Next step guidance",
    "retryable": true,
    "retry_after": 30
  }
}
Field dasar (message, type, code, param) selalu hadir. Field petunjuk (did_you_mean, suggestions, hint, retryable, retry_after, balance_usd, estimated_cost_usd) adalah ekstensi opsional untuk koreksi mandiri agen AI. Lihat panduan Agent-First API untuk detail. Endpoint yang kompatibel dengan OpenAI menggunakan tipe kesalahan gateway stabil LemonData. Endpoint yang kompatibel dengan Anthropic dan Gemini menggunakan keluarga kesalahan dan bentuk respons asli mereka sendiri.

Kode Status HTTP

CodeDeskripsi
400Bad Request - Parameter tidak valid
401Unauthorized - API key tidak valid atau hilang
402Payment Required - Saldo tidak mencukupi
403Forbidden - Akses ditolak atau model tidak diizinkan
404Not Found - Model atau sumber daya tidak ditemukan
413Payload Too Large - Ukuran input atau file melebihi batas
429Too Many Requests - Batas laju terlampaui
500Internal Server Error
502Bad Gateway - Kesalahan penyedia upstream
503Service Unavailable - Layanan sementara tidak tersedia
504Gateway Timeout - Permintaan melebihi waktu tunggu

Jenis Kesalahan

Kesalahan Otentikasi (401)

TipeKodeDeskripsi
invalid_api_keyinvalid_api_keyAPI key hilang atau tidak valid
expired_api_keyexpired_api_keyAPI key telah dicabut
from openai import OpenAI, AuthenticationError

try:
    response = client.chat.completions.create(...)
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")

Kesalahan Pembayaran (402)

TipeKodeDeskripsi
insufficient_balanceinsufficient_balanceSaldo akun terlalu rendah (endpoint kompatibel OpenAI)
insufficient_balance_errorinsufficient_balanceSaldo akun terlalu rendah (endpoint kompatibel Anthropic)
quota_exceededquota_exceededBatas penggunaan API key tercapai
from openai import OpenAI, APIStatusError

try:
    response = client.chat.completions.create(...)
except APIStatusError as e:
    if e.status_code == 402:
        print("Please top up your account balance")

Kesalahan Akses (403)

TipeKodeDeskripsi
access_deniedaccess_deniedAkses ke sumber daya ditolak
access_deniedmodel_not_allowedModel tidak diizinkan untuk API key ini
{
  "error": {
    "message": "You don't have permission to access this model",
    "type": "access_denied",
    "code": "model_not_allowed"
  }
}

Kesalahan Validasi (400)

TipeDeskripsi
invalid_request_errorParameter permintaan tidak valid
context_length_exceededInput terlalu panjang untuk model
model_not_foundModel yang diminta tidak tersedia dalam kontrak publik saat ini
{
  "error": {
    "message": "Model not found: please check the model name",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-5.4",
    "suggestions": [{"id": "gpt-5.4"}, {"id": "gpt-5-mini"}],
    "hint": "Did you mean 'gpt-5.4'? Use GET https://api.lemondata.cc/v1/models to list all available models."
  }
}
Rute publik tidak membedakan keadaan model yang salah ketik, tersembunyi, ditunda, atau tidak publik dalam badan respons. Jika sebuah model saat ini tidak tersedia melalui kontrak publik, LemonData mengembalikan model_not_found.

Kesalahan Batas Laju (429)

Ketika Anda melewati batas laju:
{
  "error": {
    "message": "Rate limit: 60 rpm exceeded",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "hint": "Rate limited. Retry after 8s. Current limit: 60/min for user role."
  }
}
Header yang disertakan:
Retry-After: 8
Header Retry-After dan field retry_after keduanya menunjukkan jumlah detik yang tepat untuk menunggu sebelum mencoba lagi.

Payload Terlalu Besar (413)

Ketika ukuran input atau file melebihi batas:
{
  "error": {
    "message": "Input size exceeds maximum allowed",
    "type": "invalid_request_error",
    "code": "payload_too_large"
  }
}
Penyebab umum:
  • File gambar terlalu besar (max 20MB)
  • File audio terlalu besar (max 25MB)
  • Teks input melebihi panjang konteks model

Kesalahan Upstream (502, 503)

TipeDeskripsi
upstream_errorPenyedia mengembalikan kesalahan
all_channels_failedTidak ada penyedia yang tersedia
timeout_errorPermintaan melebihi waktu tunggu
Ketika semua kanal gagal, respons menyertakan model alternatif:
{
  "error": {
    "message": "Model claude-opus-4-6 temporarily unavailable",
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-6", "status": "available", "tags": []},
      {"id": "gpt-5-mini", "status": "available", "tags": []}
    ],
    "hint": "Retry in 30s or switch to an available model."
  }
}

Menangani Kesalahan di Python

from openai import OpenAI, APIError, RateLimitError, APIConnectionError

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.lemondata.cc/v1"
)

def chat_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError as e:
            if attempt < max_retries - 1:
                import time
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except APIConnectionError as e:
            print(f"Connection error: {e}")
            raise
        except APIError as e:
            print(f"API error: {e.status_code} - {e.message}")
            raise

Menangani Kesalahan di JavaScript

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-api-key',
  baseURL: 'https://api.lemondata.cc/v1'
});

async function chatWithRetry(messages, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.chat.completions.create({
        model: 'gpt-4o',
        messages
      });
    } catch (error) {
      if (error instanceof OpenAI.RateLimitError) {
        if (attempt < maxRetries - 1) {
          await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
          continue;
        }
      }
      throw error;
    }
  }
}

Praktik Terbaik

Saat dibatasi oleh laju, tunggu semakin lama antara percobaan ulang:
wait_time = 2 ** attempt  # 1s, 2s, 4s, 8s...
Selalu tetapkan batas waktu yang wajar untuk menghindari permintaan yang menggantung:
client = OpenAI(timeout=60.0)  # 60 second timeout
Catat respons kesalahan lengkap termasuk ID permintaan untuk dukungan:
except APIError as e:
    logger.error(f"API Error: {e.status_code} - {e.message}")
Beberapa model memiliki persyaratan khusus (mis. max tokens, format gambar). Validasi input sebelum membuat permintaan.