Hatalar

Tüm hata yanıtları tutarlı formatta döner:

{
  "error": {
    "message": "Invalid API key",
    "type": "auth_error"
  }
}

Hata türleri

HTTP	type	Neden	Ne yapmalı?
400	invalid_request_error	Geçersiz JSON, eksik alan, bilinmeyen parametre	İsteği düzelt, schema’ya bak
401	auth_error	Geçersiz/revoke edilmiş anahtar	Dashboard’dan yeni anahtar üret
402	insufficient_balance	Kredi bakiyesi yetersiz	Dashboard > Faturalandırma’dan top-up yap
403	forbidden	Model bu hesap için kullanılamaz	Model erişimini kontrol et
404	model_not_found	model alanı bilinmeyen	Canonical ID’yi kontrol et (provider/model)
413	request_too_large	Context window aşıldı	messages içeriğini kısalt
429	rate_limit_exceeded	Rate limit aşıldı	Exponential backoff ile retry et
500	internal_error	Gateway iç hatası	Kısa süre sonra tekrar dene
502	provider_error	Sağlayıcı tarafında hata	Geçici olabilir, retry dene
503	provider_unavailable	Sağlayıcı erişilemez	Bir süre sonra tekrar dene
504	timeout	İstek zaman aşımına uğradı	Daha kısa çıktı iste veya streaming dene

Retry stratejisi

Retry sadece 429, 500, 502, 503, 504 için.
Backoff: exponential + jitter.
Max retry: 3.

Örnek (Python):

import time, random
from openai import OpenAI, APIStatusError

RETRIABLE = {429, 500, 502, 503, 504}

def call(client, payload, attempt=0):
    try:
        return client.chat.completions.create(**payload)
    except APIStatusError as e:
        if e.status_code in RETRIABLE and attempt < 3:
            time.sleep(2 ** attempt + random.random())
            return call(client, payload, attempt + 1)
        raise

Retry uygularken istemci tarafında timeout, bağlantı kopması ve çift gönderim senaryolarını da hesaba katın.