Kesalahan dan batas

Kesalahan dikembalikan dalam format API yang Anda panggil: objek error untuk OpenAI, {"type": "error", "error": {...}} untuk Anthropic, dan error dengan kolom status dan details untuk Gemini. Karena itu, SDK mengenalinya sebagai kesalahan API biasa.

• error.code dan error.reason — kelas kesalahan dari tabel di bawah; keduanya sama. error.type — nilai standar format (misalnya, invalid_request_error atau server_error).
• error.request_id (dalam Anthropic — request_id pada tingkat atas), header X-Request-ID dan bagian akhir pesan — ID permintaan.
• Dalam Gemini, kelas terdapat di error.details: ErrorInfo.reason — kode yang sama dengan huruf besar (misalnya, MODEL_OVERLOADED), domain — ailoot.ai; ID permintaan terdapat di RequestInfo.requestId.
• Dalam format Gemini, kesalahan 5xx yang tidak boleh diulang secara otomatis dan result_pending_check dikembalikan dengan status 409 dan status ABORTED: agar Gemini SDK dan CLI tidak mengulangnya secara otomatis. Kelas kesalahan terdapat di ErrorInfo.reason (misalnya, MODEL_TIMEOUT atau RESULT_PENDING_CHECK).
• Respons berformat OpenAI juga memuat kolom tingkat atas code dan message — untuk klien lama.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

Kode respons model dan pemeriksaan hasil (502, 503, dan 504) kini merujuk pada model atau permintaan: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed dan result_pending_check. Jika kode Anda membandingkan error.code dengan nilai lama, ganti dengan kode pada tabel; pemetaan kode lama ke kode baru dapat dijelaskan oleh dukungan.

• Periksa X-Should-Retry terlebih dahulu: jika false, result_pending_check atau model_timeout jangan ulangi secara otomatis. Cari Request ID dalam riwayat dasbor: hasil dan pendebitan terlihat di sana.
• Pengulangan aman jika X-Should-Retry: true diterima: tunggu Retry-After detik. Untuk 5xx, kode saja tidak cukup: hasil mungkin sudah ada. Periksa dahulu riwayat dasbor atau hubungi dukungan dengan Request ID. Ini sangat penting untuk gambar, video, musik, dan langkah agen yang panjang.
• Pengulangan tidak akan membantu: 400, 401, 402, 403, 404 — perbaiki dahulu permintaan, kunci, atau saldo.

Frekuensi dan jumlah permintaan serentak dibatasi untuk seluruh akun Anda, bukan setiap kunci. Jika terlampaui, responsnya 429 rate_limit_exceeded dengan header Retry-After: 10. Jika model itu sendiri kelebihan beban — 503 model_overloaded dengan Retry-After: 30. Jika membutuhkan beban lebih besar, hubungi dukungan.

Batas pengeluaran diatur pada kunci: batas total — 402 api_key_quota_exhausted, jendela 5 jam, 1 hari, dan 7 hari — 429 usage_limit_reached. Selengkapnya — Kunci dan alamat API.

Daftar model dapat diminta dengan saldo nol; generasi memerlukan saldo untuk ditahan. Model NVIDIA (Nemotron dan lainnya) menggunakan antrean bersama: saat beban tinggi, respons dapat terlambat atau kesalahan “model sementara kelebihan beban” dikembalikan dengan header Retry-After — coba lagi setelah waktu tersebut. Harga tersedia dalam katalog; pendebitan mengikuti aturan model lainnya.

Batas ukuran ditetapkan oleh model: konteks (jumlah token yang dapat dikirim) dan panjang respons maksimum. Keduanya tercantum dalam katalog.