Pemecahan Masalah API yang Kompatibel dengan OpenAI: Perbaiki 401, Nama Model, Streaming, dan Base URL

Pemecahan masalah API yang kompatibel dengan OpenAI menjadi jauh lebih mudah ketika Anda berhenti menganggap setiap request yang gagal sebagai "provider sedang down." Sebagian besar migrasi yang gagal berasal dari salah satu dari enam lapisan: key, base URL, keluarga endpoint, nama model, perilaku streaming, atau billing/readback.

Flatkey membantu tim menyatukan akses model, routing, billing, analitik penggunaan, dan kontrol operasional dalam satu tempat, tetapi client yang kompatibel dengan OpenAI tetap membutuhkan konfigurasi yang presisi. Sebuah request bisa terlihat benar di SDK namun tetap gagal karena client diarahkan ke root /v1 yang salah, alias model berada pada keluarga endpoint yang berbeda, atau stream dibuffer oleh proxy.

Gunakan panduan pemecahan masalah API yang kompatibel dengan OpenAI ini sebagai jalur debug yang bersih sebelum Anda mengubah kode aplikasi. Mulailah dengan curl, buktikan satu request non-streaming, tambahkan SDK, lalu tambahkan streaming, tools, dan traffic produksi satu lapisan pada satu waktu.

Jalur pemecahan masalah API yang kompatibel dengan OpenAI dalam lima menit

Sebelum Anda memeriksa kode framework, tangkap request terkecil yang seharusnya berhasil. Untuk Flatkey, gunakan base URL yang ditampilkan di console Anda saat ini. Beranda publik Flatkey saat ini menampilkan request ke https://router.flatkey.ai/v1/chat/completions, yang berarti client SDK biasanya harus menerima root /v1 sebagai base URL dan SDK harus menambahkan /chat/completions.

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Balas dengan tepat: ok"}
    ]
  }'

Jika request ini gagal, masalahnya bukan pada framework aplikasi Anda. Perbaiki key, base URL, keluarga endpoint, atau alias model terlebih dahulu. Jika berhasil, salin nilai yang sama ke SDK dan lanjutkan debug dari sana.

Aturan pemecahan masalah API yang kompatibel dengan OpenAI paling cepat adalah sederhana: jangan menguji streaming, tools, mode JSON, retry, atau workflow agen penuh sampai request teks biasa non-streaming berhasil.

Baca error sebagai lapisan, bukan sebagai putusan akhir

Gunakan status code untuk menentukan apa yang harus diubah berikutnya.

Gejala	Lapisan yang mungkin	Apa yang harus diperiksa pertama
401, invalid_api_key, atau error autentikasi	Key dan auth header	Format Bearer, sumber key, spasi yang ikut tersalin, key provider versus key gateway
403 atau permission denied	Akun, project, atau policy	IP allowlist, keanggotaan project, persetujuan model, izin endpoint
404, model_not_found, atau model tidak dikenal	Katalog model dan keluarga endpoint	Alias model yang tepat, status model diaktifkan, /chat/completions versus /responses versus endpoint lain
400 request tidak valid	Bentuk payload	Field wajib, parameter yang tidak didukung, skema tool, format pesan
Stream terhubung tetapi tidak ada token yang muncul	Jalur streaming	stream: true, parser SSE, buffering proxy, dukungan stream endpoint
Request berhasil tetapi usage hilang	Readback dan billing	Request pembanding non-streaming, record dashboard, perilaku event stream akhir
429, 500, 502, 503, atau 504	Rate, kapasitas, atau upstream	Backoff, volume request, halaman status, kebijakan retry, route fallback

Panduan error OpenAI sendiri memperlakukan 401 sebagai masalah autentikasi, 429 sebagai masalah rate atau kuota, dan respons 500/503 sebagai kondisi server atau overload yang dapat di-retry. Gateway yang kompatibel dengan OpenAI dapat menambahkan detailnya sendiri, jadi simpan body respons dan request ID saat Anda melakukan eskalasi.

Perbaiki 401 sebelum mengganti model

401 adalah detour paling umum dalam pemecahan masalah API yang kompatibel dengan OpenAI karena terlihat seperti masalah model atau route padahal biasanya masalah autentikasi.

Periksa hal-hal ini secara berurutan:

1. Request memiliki tepat satu header Authorization: Bearer ....
2. Key yang digunakan adalah key Flatkey saat memanggil Flatkey, bukan key OpenAI, Anthropic, Google, atau key pengujian langsung.
3. Key tidak memiliki tanda kutip yang ikut tersalin, newline, prefix tak terlihat, atau spasi di akhir.
4. Key dimuat dari environment tempat proses benar-benar berjalan, bukan hanya dari shell Anda.
5. Akun, project, tim, atau policy IP mengizinkan route tersebut.

Gunakan pengecekan shell singkat yang tidak mencetak key:

test -n "$FLATKEY_API_KEY" && echo "key is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c

Jika curl berhasil tetapi SDK mengembalikan 401, periksa nama environment variable. Client Python OpenAI membaca OPENAI_API_KEY secara default, dan client Node membaca OPENAI_API_KEY secara default. Jika aplikasi Anda masih mengekspor OPENAI_API_KEY dengan key provider langsung yang lama, SDK mungkin mengabaikan key gateway baru Anda kecuali Anda mengirim api_key atau apiKey secara eksplisit.

Perbaiki base URL tanpa menggandakan endpoint

Kesalahan base URL biasanya jatuh ke dalam dua pola:

1. SDK menerima endpoint lengkap, seperti https://router.flatkey.ai/v1/chat/completions, lalu menambahkan /chat/completions lagi.
2. SDK hanya menerima domain, seperti https://router.flatkey.ai, dan tidak pernah mencapai route /v1 yang kompatibel dengan OpenAI.

Untuk Python, berikan base_url atau set OPENAI_BASE_URL. Source client Python resmi juga akan kembali ke https://api.openai.com/v1 saat tidak ada custom base URL yang diberikan.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: ok"}],
)

print(response.choices[0].message.content)

Untuk Node, berikan baseURL atau set OPENAI_BASE_URL. Client Node resmi mendokumentasikan baseURL sebagai override untuk root API OpenAI default.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: ok" }],
});

console.log(response.choices[0]?.message?.content);

Jika langkah pemecahan masalah API yang kompatibel dengan OpenAI ini masih gagal, log base URL yang terselesaikan saat startup proses. Jangan log key.

Pisahkan nama model dari keluarga endpoint

"Model tidak ditemukan" bisa berarti alias-nya salah, tetapi juga bisa berarti alias dikirim ke keluarga endpoint yang salah. Model yang berfungsi untuk chat completions mungkin tidak diekspos melalui Responses, Messages, images, video, atau embeddings dengan bentuk payload yang sama.

Jalankan checklist ini sebelum mengganti nama model di produksi:

Pemeriksaan	Mengapa ini penting
Konfirmasi alias model yang tepat di console Flatkey saat ini	Alias gateway dapat berbeda dari nama pemasaran provider langsung
Konfirmasi keluarga endpoint	/v1/chat/completions dan /v1/responses memiliki bentuk request yang berbeda
Hapus parameter opsional	Opsi yang tidak didukung dapat menyembunyikan masalah model yang sebenarnya
Coba request singkat tanpa streaming	Request sederhana mengisolasi route dari parsing stream
Catat body yang gagal dan timestamp	Support dan audit review memerlukan model, route, dan error yang tepat

Dokumentasi model eksternal OpenAI menggunakan ide yang sama untuk custom endpoint: berikan URL endpoint, tentukan slug model, dan jalankan panggilan verifikasi. Perlakukan setup gateway Anda dengan cara yang sama. Simpan peta model yang disetujui dalam code daripada membiarkan setiap service mengirim string model mentah.

Debug streaming setelah non-streaming berfungsi

Streaming harus menjadi pengujian tahap kedua. Referensi Chat Completions OpenAI mengembalikan objek completion chat JSON atau urutan streamed dari objek chunk completion chat. API Responses juga mendukung text/event-stream saat stream diaktifkan.

Gunakan probe stream langsung:

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

Jika request non-streaming berfungsi dan stream tidak, periksa path stream:

• Konfirmasi respons menggunakan content type yang kompatibel dengan SSE.
• Nonaktifkan middleware API client yang men-buffer seluruh respons sebelum mengembalikannya.
• Nonaktifkan buffering reverse proxy untuk route ini.
• Periksa apakah parser frontend Anda mengharapkan chunk Chat Completions sementara route Anda mengembalikan event Responses.
• Bandingkan dengan checklist streaming Flatkey yang sudah ada di /blog/openai-compatible-streaming-sse-test.

Langkah pemecahan masalah API yang kompatibel dengan OpenAI ini sangat penting di serverless dan tool otomasi. Beberapa wrapper mengembalikan status HTTP yang sukses sambil menyembunyikan fakta bahwa tidak ada token yang sampai ke caller sampai stream ditutup.

Tambahkan tools hanya setelah request dasar bersih

Tool calling menambahkan lapisan kegagalan lain. Sebuah gateway, route, atau model yang dipilih mungkin menerima pesan chat biasa tetapi menolak schema tool, tool_choice, parallel tool calls, atau pengaturan strict structured output.

Gunakan tangga tiga request:

1. Request teks biasa dengan model yang sama.
2. Request yang sama dengan satu schema fungsi kecil.
3. Schema tool produksi lengkap.

Jika request 1 berfungsi dan request 2 gagal, Anda tidak lagi sedang debug auth atau base URL. Anda sedang debug kapabilitas model, keluarga endpoint, atau dukungan schema. Hapus field opsional, persingkat deskripsi, dan verifikasi apakah route model yang dipilih mendukung perilaku tool yang Anda butuhkan.

Buktikan pembacaan ulang usage dan billing

Jangan menyelesaikan pemecahan masalah API yang kompatibel dengan OpenAI pada tahap "respons mengembalikan teks." Untuk migrasi produksi, Anda juga perlu membuktikan bahwa permintaan terlihat di tempat tim keuangan dan operasional akan meninjaunya.

Setelah smoke test berhasil, catat:

Bukti	Yang dibuktikan
Stempel waktu dan rute permintaan	Jalur gateway mana yang menerima traffic
Alias model	Model terkonfigurasi mana yang diminta
Status respons dan ID permintaan	Apa yang bisa dilacak oleh dukungan
Objek usage atau jumlah token	Apakah aplikasi dapat mencatat pendorong biaya
Dashboard atau pembacaan ulang billing	Apakah keuangan dapat merekonsiliasi pengeluaran
Event fallback atau retry, jika ada	Apakah kebijakan routing mengubah jalur

Flatkey diposisikan di sekitar satu kunci, harga yang jelas, billing terpadu, dan dashboard untuk kunci, usage, dan routing. Untuk migrasi, pasangkan smoke test rekayasa dengan pemeriksaan pembacaan ulang usage di konsol sebelum Anda memindahkan traffic nyata.

Alur kerja pemecahan masalah yang aman untuk produksi

Gunakan urutan ini ketika migrasi API yang kompatibel dengan OpenAI gagal:

1. Jalankan satu permintaan curl non-streaming dengan base URL konsol saat ini, satu kunci, dan satu alias model yang disetujui.
2. Perbaiki 401 atau 403 sebelum mengubah payload.
3. Perbaiki komposisi base URL sebelum mengubah versi SDK.
4. Perbaiki alias model dan family endpoint sebelum mengubah kebijakan retry.
5. Tambahkan SDK dengan api_key atau apiKey yang eksplisit dan base_url atau baseURL.
6. Tambahkan streaming dan verifikasi bahwa klien menerima event inkremental.
7. Tambahkan tools atau output terstruktur satu fitur pada satu waktu.
8. Periksa pembacaan ulang usage dan billing.
9. Pindahkan nilai yang bekerja ke config yang siap rollback.

Urutan itu mencegah pemecahan masalah API yang kompatibel dengan OpenAI menjadi sesi tebak-tebakan. Setiap langkah entah membuktikan satu lapisan atau memberi Anda kegagalan yang lebih kecil untuk diperbaiki.

Kapan Flatkey membantu

Flatkey berguna ketika masalah utamanya adalah sprawl operasional: terlalu banyak kunci provider, akses model yang tidak konsisten, usage yang sulit ditinjau, dan jalur billing yang terpisah. Gateway terpadu tidak menghilangkan kebutuhan untuk menguji family endpoint, alias model, streaming, tools, dan pembacaan ulang billing, tetapi ini memberi tim satu tempat untuk menstandarkan pemeriksaan tersebut.

Jika Anda sedang memigrasikan aplikasi, pasangkan panduan ini dengan panduan migrasi yang kompatibel dengan OpenAI dari Flatkey di /blog/openai-compatible-api-migration dan daftar periksa smoke test di /blog/ai-api-smoke-test-checklist.

Ketika Anda siap menguji alur kerja dengan kunci Flatkey, mulai di /sign-up dan buat smoke test pertama cukup kecil untuk diperiksa secara manual.

Pertanyaan yang sering diajukan

Mengapa API yang kompatibel dengan OpenAI saya mengembalikan 401 saat kunci sudah disetel?

Prosesnya mungkin membaca variabel lingkungan yang berbeda dari yang Anda ubah, atau kunci tersebut mungkin milik provider yang salah. Periksa nama variabel yang terselesaikan, header Authorization: Bearer, whitespace yang ikut tersalin, dan kebijakan akun atau IP apa pun.

Haruskah base URL SDK menyertakan /chat/completions?

Biasanya tidak. Berikan SDK base URL /v1, lalu biarkan SDK menambahkan endpoint. Memberikan endpoint penuh sering kali menciptakan path ganda.

Mengapa model berfungsi tanpa streaming tetapi gagal dengan stream: true?

Rute dasar mungkin benar sementara jalur streaming diblokir oleh buffering middleware, ketidaksesuaian parser SSE, atau kombinasi route/model yang tidak mendukung streaming. Uji dengan curl -N sebelum men-debug kode frontend.

Mengapa "model tidak ditemukan" terjadi dengan nama model yang valid?

Alias tersebut mungkin valid di satu family endpoint dan tidak valid di family lain, atau gateway mungkin mengekspos alias yang berbeda dari provider langsung. Konfirmasi alias konsol saat ini dan family endpoint bersama-sama.

Apa yang harus saya uji sebelum mengirim traffic produksi?

Uji satu permintaan non-streaming, satu permintaan SDK, satu stream, satu panggilan tools yang representatif jika aplikasi Anda menggunakan tools, satu jalur kegagalan, dan satu catatan billing/pembacaan ulang. Lalu simpan config rollback untuk rute provider sebelumnya.

Pemecahan masalah API yang kompatibel dengan OpenAI bukan tentang menghafal setiap error provider. Ini tentang membuktikan jalur dari kunci ke base URL, dari base URL ke family endpoint, dari family endpoint ke alias model, dan dari respons berhasil ke catatan usage. Ketika lapisan-lapisan itu jelas, perpindahan traffic melalui Flatkey menjadi migrasi yang terkendali, bukan sesi debug larut malam.