Error & retry · Dokumentasi Laras Router

Error memakai format error OpenAI, jadi SDK OpenAI memunculkannya sebagai exception biasa. Buat logika berdasarkan error.code (dan error.type), jangan berdasarkan teks pesan.

402 Payment Required

{
  "error": {
    "message": "Insufficient balance. Top up to continue.",
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "param": null
  }
}

message berbahasa Inggris secara default. Kirim Accept-Language: id untuk menerimanya dalam Bahasa Indonesia. code dan type selalu sama di semua bahasa.

Kode error

Status	Kode	Tipe	Arti	Yang perlu dilakukan
400	`invalid_request`	`invalid_request_error`	Body bukan JSON yang valid atau tidak menyebutkan model.	Perbaiki request. Jangan diulang.
400	`max_tokens_exceeded`	`invalid_request_error`	`max_tokens` atau `max_completion_tokens` di atas 384.000.	Turunkan nilainya. Jangan diulang.
400	`unsupported_content`	`invalid_request_error`	Ada pesan yang berisi gambar atau bagian non-teks lainnya.	Kirim teks saja. Jangan diulang.
401	`invalid_api_key`	`invalid_request_error`	Kunci tidak ada, formatnya salah, sudah dicabut, atau tidak dikenal.	Periksa header dan kuncinya. Jangan diulang.
402	`insufficient_credit`	`insufficient_quota`	Saldo tersedia Anda $0.00 atau kurang.	Isi saldo, lalu coba lagi.
402	`key_budget_exceeded`	`insufficient_quota`	Request ini akan membuat kunci melampaui anggaran bulanannya.	Naikkan atau hapus anggaran di konsol, atau tunggu bulan berikutnya (WIB).
403	`insufficient_scope`	`insufficient_permissions`	Kunci tidak memiliki scope `chat:write`.	Gunakan kunci dengan scope yang benar. Jangan diulang.
404	`model_not_found`	`invalid_request_error`	ID model tidak tersedia.	Gunakan `deepseek-flash`. Jangan diulang.
404	`not_found`	`invalid_request_error`	Endpoint tidak dikenal.	Periksa path; base URL berakhiran `/v1`.
405	`method_not_allowed`	`invalid_request_error`	Metode HTTP salah untuk endpoint ini.	Gunakan `POST` untuk chat completions, `GET` untuk models.
413	`request_too_large`	`invalid_request_error`	Body melebihi batas ukuran request.	Persingkat prompt atau riwayat percakapan.
429	`rate_limit_exceeded`	`rate_limit_exceeded`	Lebih dari 300 request dalam satu menit pada kunci ini.	Tunggu sesuai `Retry-After`, lalu coba lagi.
429	`concurrency_limit_exceeded`	`rate_limit_exceeded`	Lebih dari 16 request berjalan bersamaan pada kunci ini.	Tunggu sesuai `Retry-After` atau sampai ada request yang selesai.
429	`ip_rate_limited`	`rate_limit_exceeded`	Terlalu banyak request dari satu alamat IP.	Tunggu sesuai `Retry-After`, lalu coba lagi.
500	`internal_error`	`api_error`	Kesalahan server yang tidak terduga.	Coba lagi dengan backoff.
502	`provider_unavailable`	`api_error`	Penyedia model gagal atau tidak bisa dihubungi.	Coba lagi dengan backoff.
503	`billing_unavailable`	`api_error`	Billing sementara tidak tersedia; request tidak dijalankan.	Coba lagi dengan backoff. Anda tidak ditagih.
503	`service_unavailable`	`api_error`	Layanan sementara tidak tersedia.	Coba lagi dengan backoff.

Error lain yang dikembalikan penyedia model — misalnya 400 untuk kombinasi parameter yang tidak didukungnya — diteruskan dengan body error asli dari penyedia.

Kapan mencoba lagi

Ulangi hanya 429, 500, 502, dan 503. Error lainnya perlu perubahan pada request, kunci, atau saldo Anda terlebih dahulu.

429: tunggu sejumlah detik sesuai header Retry-After sebelum mencoba lagi.
5xx: gunakan exponential backoff dengan jitter, misalnya 1 dtk, 2 dtk, 4 dtk, dan berhenti setelah beberapa kali percobaan.
Setiap percobaan ulang adalah request baru. Request itu ditahan, diukur, dan ditagih sendiri.

SDK resmi OpenAI sudah otomatis mengulang respons 429 dan 5xx beberapa kali dengan backoff, dan menghormati Retry-After. Anda bisa menaikkan batasnya:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.larasrouter.com/v1",
    api_key=os.environ["LARAS_API_KEY"],
    max_retries=4,
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.larasrouter.com/v1",
  apiKey: process.env.LARAS_API_KEY,
  maxRetries: 4,
});

Tangani error berdasarkan kode

Python

import openai

try:
    response = client.chat.completions.create(
        model="deepseek-flash",
        messages=[{"role": "user", "content": "Halo"}],
    )
except openai.APIStatusError as e:
    # SDK menyediakan error.code dari body respons sebagai e.code.
    if e.code == "insufficient_credit":
        notify_owner("Saldo Laras Router habis — isi saldo untuk melanjutkan.")
    elif e.code == "key_budget_exceeded":
        notify_owner("Kunci ini sudah mencapai anggaran bulanannya.")
    else:
        raise

Request yang gagal dan tagihan

Request yang ditolak sebelum sampai ke model — semua 400, 401, 402, 403, 404, 413, 429 dari Laras Router — tidak pernah ditagih.
Request yang ditolak penyedia model dengan 4xx tidak ditagih; hold-nya dilepas.
Request yang gagal dengan 5xx, timeout, atau terputus tetap ditahan hold-nya selama kami melakukan rekonsiliasi. Anda mungkin ditagih untuk pemakaian yang dilaporkan penyedia; jika tidak ada, hold dilepas tanpa biaya.

Request ID

Respons untuk request yang sudah sampai ke tahap billing membawa header X-Laras-Request-ID. Header ini mengidentifikasi tagihan dan hold untuk request tersebut. Sertakan saat Anda menghubungi support soal tagihan. Request yang ditolak sebelum hold dibuat — misalnya 401 — mungkin tidak membawanya.