AI Coding Assistant Lingma:Error

Selubung Error

Semua respons error mengikuti struktur JSON berikut:

{
  "type": "error",
  "error": {
    "type": "[error_type]",
    "message": "[deskripsi yang dapat dibaca manusia]",
    "param": "[nama parameter yang bermasalah, opsional]"
  }
}

Deskripsi bidang

Jenis Kesalahan

Detail jenis kesalahan

400 — invalid_request_error

Format permintaan atau parameter tidak valid.

Pemicu Umum:

• Bidang wajib tidak ditemukan (misalnya, name)
• Ketidakcocokan tipe bidang (misalnya, angka diberikan padahal string yang diharapkan)
• Body melebihi batas 4 MB
• JSON tidak valid

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

# Contoh pemicu: tidak menyertakan bidang nama
curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'

401 — authentication_error

Autentikasi gagal.

Pemicu Umum:

• Header Authorization tidak ditemukan
• PAT tidak valid
• PAT telah kedaluwarsa atau dicabut
• x-api-key digunakan alih-alih token bearer

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Kunci API atau token tidak valid."
  }
}

# Contoh pemicu: token tidak valid
curl -s https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

Terautentikasi tetapi tidak diizinkan.

Pemicu Umum:

• PAT tidak memiliki akses ke Agent target (pengguna atau organisasi berbeda)
• Cakupan PAT tidak mencakup operasi ini
• Mencoba melakukan operasi pada resource yang telah diarsipkan dan terkunci

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Anda tidak memiliki izin untuk mengakses agen ini."
  }
}

# Contoh pemicu: mengakses Agen pengguna lain
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_other_user_123 \
  -H "Authorization: Bearer $QODER_PAT"

404 — not_found_error

Sumber daya tujuan tidak ditemukan.

Pemicu Umum:

• ID Agent, Session, atau Environment tidak ditemukan
• Sumber daya telah dihapus
• Kesalahan pengetikan pada path URL

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Agen tidak ditemukan: agent_nonexistent_123"
  }
}

# Contoh pemicu: Agen yang tidak ada
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_nonexistent_123 \
  -H "Authorization: Bearer $QODER_PAT"

409 — conflict_error

Konflik status sumber daya mencegah operasi.

Pemicu Umum:

• Kunci idempotensi yang sama digunakan kembali dengan badan permintaan yang berbeda
• Mengoperasikan Session yang telah dihentikan tugasnya
• Membuat duplikat sumber daya dengan nama unik

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Permintaan dengan kunci idempotensi ini telah diproses dengan parameter yang berbeda."
  }
}

500 — api_error

Kesalahan server internal.

Pemicu Umum:

• Layanan sementara tidak tersedia
• Kegagalan komponen internal
• Timeout koneksi database

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again later."
  }
}

Praktik terbaik penanganan error

1. Buat branch berdasarkan error.type alih-alih kode status HTTP.
2. Catat error.message untuk keperluan diagnostik.
3. Periksa error.param untuk menemukan bidang yang bermasalah.
4. Jangan lakukan retry terhadap error 4xx kecuali jika permintaan telah dimodifikasi.
5. Lakukan retry terhadap error 5xx dengan exponential backoff (maksimal 3 kali percobaan).

# Permintaan dengan penanganan kesalahan
response=$(curl -s -w "\n%{http_code}" \
  https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  error_type=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['error']['type'])")
  echo "API error: $error_type"
fi