Source: https://ailoot.ai/docs/ms/errors/
Canonical: https://ailoot.ai/docs/ms/errors/
Language: ms

[Bantuan](https://ailoot.ai/docs/ms/) 

# Ralat dan had

[Markdown](https://ailoot.ai/docs/ms/errors/index.md)

Kod respons, maksudnya dan tindakan yang perlu diambil. Semua ralat dalam JSON dan disertakan Request ID.

## [](https://ailoot.ai/docs/ms/errors/#format)Format ralat

Ralat diterima dalam format API yang anda panggil: objek `error` untuk OpenAI, `{"type": "error", "error": {...}}` untuk Anthropic dan `error` dengan medan `status` dan `details` untuk Gemini. Oleh itu, SDK mengenalinya sebagai ralat API biasa.

- `error.code` dan `error.reason` — kelas ralat daripada jadual di bawah; kedua-duanya sama. `error.type` — nilai standard bagi format (contohnya, `invalid_request_error` atau `server_error`).
- `error.request_id` (dalam Anthropic — `request_id` pada peringkat teratas), pengepala `X-Request-ID` dan penghujung teks mesej — pengecam permintaan.
- Dalam Gemini, kelas terdapat dalam `error.details`: `ErrorInfo.reason` — kod yang sama dalam huruf besar (contohnya, `MODEL_OVERLOADED`), `domain` — `ailoot.ai`; pengecam permintaan terdapat dalam `RequestInfo.requestId`.
- Dalam format Gemini, ralat 5xx yang tidak boleh dicuba semula secara automatik dan `result_pending_check` diterima dengan status 409 dan `status` `ABORTED`: dengan cara ini, Gemini SDK dan CLI tidak mengulanginya sendiri. Kelas ralat terdapat dalam `ErrorInfo.reason` (contohnya, `MODEL_TIMEOUT` atau `RESULT_PENDING_CHECK`).
- Respons berformat OpenAI turut mengandungi medan peringkat teratas `code` dan `message` — untuk klien lama.

```json
{
  "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. …"
}
```

```json
{
  "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"
}
```

```json
{
  "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"
      }
    ]
  }
}
```

“Nothing was charged” bermaksud tiada wang dicaj. Jika X-Should-Retry: false diterima — jangan cuba semula secara automatik, semak Request ID dalam sejarah terlebih dahulu.

## [](https://ailoot.ai/docs/ms/errors/#codes)Kod ralat

| HTTP | Kelas (reason) | Perkara yang berlaku | Tindakan |
| --- | --- | --- | --- |
| 400 | `invalid_request` | Permintaan tidak sah: badan atau parameter tidak betul; model tidak menyokong medan, lampiran atau alat dalam permintaan; kunci dihantar dalam alamat | Betulkan permintaan berdasarkan mesej ralat: buang medan, lampiran atau alat yang tidak disokong; hantar kunci dalam pengepala. Penolakan kerana medan, lampiran atau alat yang tidak disokong berlaku sebelum rizab — tiada caj dikenakan |
| 400 | `context_length_exceeded` | Permintaan melebihi konteks model | Pendekkan sejarah atau gunakan model dengan konteks lebih besar |
| 400 | `content_policy_violation` | Permintaan ditolak oleh peraturan model | Ubah cara permintaan ditulis |
| 401 | `invalid_api_key` | Kunci tiada atau tidak sah | Pastikan kunci dihantar sepenuhnya |
| 401 | `api_key_disabled` | Kunci dinyahaktifkan | Aktifkan kunci atau cipta kunci baharu |
| 402 | `insufficient_balance`, `insufficient_quota` | Baki tersedia tidak mencukupi walaupun untuk rizab minimum (`insufficient_quota` — keadaan yang sama dalam bentuk yang biasa digunakan oleh OpenAI SDK) | Tambah nilai baki atau kurangkan max\_tokens |
| 402 | `api_key_quota_exhausted` | Jumlah had perbelanjaan kunci telah habis digunakan | Naikkan had kunci dalam panel pengguna |
| 402 | `payment_disputed` | Akaun mempunyai hutang akibat pembayaran yang dipertikaikan | Permintaan baharu digantung sehingga hutang dilangsaikan — hubungi sokongan |
| 403 | `api_key_expired` | Tempoh sah kunci telah tamat | Cipta kunci baharu |
| 403 | `account_inactive` | Akaun anda dinyahaktifkan | Hubungi sokongan |
| 403 | `permission_denied` | Kunci tidak dibenarkan membuat permintaan ini (contohnya, berdasarkan IP) | Semak sekatan kunci |
| 404 | `model_not_found` | Model tersebut tidak wujud | Semak ID berdasarkan /v1/models |
| 404 | `unsupported_endpoint` | Model tidak berfungsi dalam format ini | Pilih format atau model lain |
| 404 | `not_found` | Laluan atau objek tersebut tidak wujud (contohnya, tugasan) | Semak alamat dan pengecam |
| 409 | `duplicate_request` | Operasi dengan kunci idempotensi yang sama telah diterima dan mungkin telah selesai | Semak hasil operasi pertama, jangan hantar operasi baharu |
| 409 | `not_ready`, `video_not_ready` | Video atau tugasan lain belum siap | Semak status kemudian |
| 409, 503 | `result_pending_check` | Kami sedang menyemak hasil permintaan. Bagi tugasan video, ini ialah bendera `result_pending_check: true` dalam respons status, manakala status tugasan kekal `in_progress` | Jangan hantar semula permintaan — status akan dipaparkan dalam sejarah (GET https://ailoot.ai/api/v1/usage). Jangan cipta semula tugasan video: semak kemudian melalui GET /v1/videos/{id} |
| 410 | `model_retired` | Model telah ditamatkan perkhidmatannya | Pilih versi baharu dalam GET /v1/models |
| 413 | `request_too_large` | Badan permintaan terlalu besar | Kecilkan fail atau pendekkan sejarah |
| 429 | `rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full` | Terlalu banyak permintaan atau permintaan serentak daripada akaun anda | Tunggu (pengepala `Retry-After`, biasanya 10 saat) dan cuba semula |
| 429 | `usage_limit_reached` | Had perbelanjaan kunci bagi tetingkap masa telah habis digunakan (5 jam, 1 hari atau 7 hari) | Tunggu sehingga tetingkap diperbaharui atau naikkan had kunci |
| 500 | `internal_error` | Ralat Ailoot | Hubungi sokongan dengan Request ID |
| 502 | `invalid_model_response`, `empty_response`, `incomplete_response` | Model mengembalikan respons yang tidak sah, kosong atau tidak lengkap | Cari Request ID dalam sejarah akaun. Jika terdapat hasil atau caj di situ, pengulangan akan menghasilkan permintaan berbayar kedua. Ketiadaan rekod tidak membuktikan bahawa permintaan belum dihantar atau belum dijalankan: jangan ulang penghantaran yang statusnya tidak diketahui; hubungi sokongan dengan Request ID. |
| 502 | `result_not_delivered` | Hasil tidak dihantar akibat kesilapan Ailoot; rizab atau caj telah dipulangkan | Permintaan boleh dihantar semula |
| 503 | `model_overloaded` | Model terlebih beban buat sementara waktu | Jika X-Should-Retry: true — cuba semula selepas bilangan saat dalam Retry-After; jika false — semak Request ID dalam sejarah terlebih dahulu |
| 503 | `model_unavailable` | Model tidak tersedia buat sementara waktu | Pilih model lain. Jika X-Should-Retry: true — cuba semula selepas bilangan saat dalam Retry-After; jika false — semak Request ID dalam sejarah terlebih dahulu |
| 503 | `service_unavailable` | Gangguan sementara pada pihak Ailoot | Jika X-Should-Retry: true — cuba semula selepas bilangan saat dalam Retry-After; jika false — semak Request ID dalam sejarah terlebih dahulu |
| 503 | `charge_not_confirmed` | Respons tidak diberikan: caj tidak dapat disahkan; rizab dikembalikan dan tiada wang dicaj | Jika X-Should-Retry: true — cuba semula selepas bilangan saat dalam Retry-After; jika false — semak Request ID dalam sejarah terlebih dahulu |
| 504 | `model_timeout` | Model tidak memberikan respons dalam tempoh yang ditetapkan; hasil masih mungkin muncul | Jangan hantar semula permintaan sebelum menyemak Request ID dalam sejarah |

Kod respons model dan semakan hasil (502, 503 dan 504) kini merujuk kepada model atau permintaan: `model_unavailable`, `model_timeout`, `invalid_model_response`, `incomplete_response`, `charge_not_confirmed` dan `result_pending_check`. Jika kod anda membandingkan `error.code` dengan nilai lama, gantikannya dengan kod dalam jadual; padanan antara kod lama dan baharu boleh diperoleh daripada [sokongan](https://ailoot.ai/docs/ms/support/).

## [](https://ailoot.ai/docs/ms/errors/#retry)Bila hendak mencuba semula permintaan

- **Semak X-Should-Retry terlebih dahulu**: jika nilainya `false`, `result_pending_check` atau `model_timeout` jangan cuba semula secara automatik. Cari Request ID dalam sejarah panel pengguna: hasil dan caj dipaparkan di situ.
- **Percubaan semula selamat apabila X-Should-Retry: true diterima**: tunggu `Retry-After` saat. Untuk 5xx, kod sahaja tidak mencukupi: hasil mungkin sudah wujud. Semak sejarah dalam panel pengguna terlebih dahulu atau hubungi sokongan dengan Request ID. Ini amat penting untuk imej, video, muzik dan langkah ejen yang panjang.
- **Percubaan semula tidak membantu**: 400, 401, 402, 403, 404 — betulkan permintaan, kunci atau baki terlebih dahulu.

SDK OpenAI dan Anthropic biasanya mengulangi permintaan secara automatik apabila berlaku ralat rangkaian dan 5xx. Untuk penjanaan, nyahaktifkan ciri ini (`max_retries=0`) dan semak `X-Should-Retry` sebelum percubaan baharu. Respons yang hilang tidak bermaksud permintaan tidak dilaksanakan.

## [](https://ailoot.ai/docs/ms/errors/#limits)Had

Kadar dan bilangan permintaan serentak dihadkan untuk seluruh akaun anda, bukan setiap kunci secara berasingan. Jika had dilampaui, respons 429 diterima `rate_limit_exceeded` dengan pengepala `Retry-After: 10`. Jika model itu sendiri terlebih beban — 503 `model_overloaded` dengan `Retry-After: 30`. Jika anda memerlukan beban yang lebih tinggi, hubungi [sokongan](https://ailoot.ai/docs/ms/support/).

Had perbelanjaan ditetapkan pada kunci: jumlah had — 402 `api_key_quota_exhausted`, tetingkap 5 jam, 1 hari dan 7 hari — 429 `usage_limit_reached`. Maklumat lanjut — [Kunci dan alamat API](https://ailoot.ai/docs/ms/keys/#key).

## [](https://ailoot.ai/docs/ms/errors/#nvidia)Model NVIDIA: baris gilir

Senarai model boleh diminta walaupun baki sifar; penjanaan memerlukan baki untuk rizab. Model NVIDIA (Nemotron dan model lain) menggunakan baris gilir bersama: ketika beban tinggi, respons mungkin tiba lebih lewat atau ralat “model terlebih beban buat sementara waktu” diterima dengan pengepala Retry-After — cuba semula selepas tempoh yang dinyatakan. Harga terdapat dalam katalog, dan caj dikenakan seperti model lain.

Had saiz ditentukan oleh model: konteks (bilangan token yang boleh dihantar) dan panjang maksimum respons. Had ini dinyatakan dalam [katalog](https://ailoot.ai/models/ms/).

## Sejarah dan perbelanjaan

[Sejarah dan perbelanjaan](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/ms/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN`

`JWT ≠ sk-…` · [Log masuk dan sesi](https://ailoot.ai/docs/ms/cabinet/auth/)

Masih ada soalan? Hantar Request ID dan penerangannya — kami akan membantu menyiasatnya.[Hubungi sokongan](mailto:support@ailoot.ai)

## Ailoot · Syarikat dan portfolio projeknya





Ailoot berteraskan pengalaman operasi yang mantap, pangkalan pelanggan yang besar, perkhidmatan yang stabil dan pemantauan KPI berterusan.





Syarikat dan portfolio projeknya: jutaan pelanggan; jualan bernilai berbilion setiap bulan.





Ailoot menggunakan pengalaman operasi ini untuk akses API kepada ciri AI dalam produk pelanggan, ejen, aplikasi dan automasi.