Menangani error Compliance API

Halaman ini mencantumkan pesan respons yang dikembalikan oleh setiap endpoint Compliance API yang terdokumentasi, penyebabnya, dan perbaikannya.

Compliance API mengembalikan error dalam format error Anthropic standar: kode status non-2xx, header respons request-id, dan body JSON dengan objek error yang berisi type dan message. Sertakan nilai header request-id saat Anda mengeskalasi ke dukungan.

{
  "error": {
    "type": "authentication_error",
    "message": "The API key provided is invalid or has been revoked."
  }
}

Cocokkan berdasarkan error.type, bukan berdasarkan string pesan. Pesan cukup stabil untuk disalin ke dalam runbook tetapi mungkin diubah kata-katanya seiring waktu; nilai type adalah bagian dari kontrak API.

Tabel berikut memberi tahu Anda secara sekilas apakah perlu mencoba ulang. Setiap bagian berikutnya menunjukkan body error secara verbatim dan perbaikannya.



400 Bad Request

Permintaan valid secara sintaksis tetapi berisi parameter yang ditolak oleh server. Perbaiki parameter dan coba ulang.



Format timestamp tidak valid

Type: invalid_request_error

The `created_at.gte` parameter contains an invalid timestamp format. Timestamps must be provided in RFC 3339 format e.g., "2024-03-01T00:00:00Z". Got "2024-01-01".

Penyebab: Nilai created_at.* atau updated_at.* (.gte, .gt, .lte, .lt) tidak dapat diurai sebagai datetime. Pesan menyebutkan parameter yang gagal dan menampilkan kembali nilai yang dikirim.

Perbaikan: Kirim timestamp RFC 3339 lengkap termasuk waktu dan zona waktu, misalnya, 2024-03-01T00:00:00Z atau 2024-03-01T00:00:00+00:00.



Limit tidak valid

Type: invalid_request_error

The limit parameter must be between 1 and 1000, inclusive. Got 1500.

Penyebab: Parameter query limit berada di luar rentang yang diterima. Batas yang disebutkan dalam pesan mencerminkan nilai maksimum untuk endpoint spesifik yang dipanggil.

Perbaikan: Kirim limit dalam rentang yang diterima endpoint. Setiap endpoint list memiliki rentang limit masing-masing; lihat batasan parameter pada halaman referensi Compliance API yang sesuai.



ID paginasi tidak valid

Type: invalid_request_error

Invalid `after_id`. No activity found for `after_id` "activity_invalid123"

Penyebab: Cursor after_id atau before_id tidak dapat didekode sebagai cursor opaque atau diurai sebagai ID aktivitas.

Perbaikan: Perlakukan cursor paginasi sebagai string opaque. Selalu salin nilai first_id atau last_id yang dikembalikan oleh halaman sebelumnya; berhenti ketika has_more bernilai false. Jangan membangun cursor dari ID objek.

Endpoint direktori dan proyek (organizations, users, roles, role permissions, groups, group members, projects, dan project attachments) melakukan paginasi dengan token page opaque alih-alih after_id dan before_id. Saran yang sama berlaku: teruskan nilai next_page dari respons sebelumnya tanpa diubah, dan berhenti ketika has_more bernilai false. Token page yang salah format mengembalikan 400 invalid_request_error yang sama seperti after_id atau before_id yang salah format.



401 Unauthorized

Header x-api-key tidak ada atau tidak cocok dengan kunci yang dikenal. Kunci yang valid dengan scope yang salah mengembalikan 403 Forbidden sebagai gantinya.



Kunci API tidak valid

Type: authentication_error

The API key provided is invalid or has been revoked.

Penyebab: Kunci di x-api-key tidak ada, telah dihapus, atau telah dinonaktifkan. Header x-api-key yang hilang atau kosong mengembalikan body yang sama, jadi periksa baik secret store Anda maupun status pencabutan kunci.

Perbaikan: Konfirmasi nilai kunci, periksa bahwa kunci belum dihapus di claude.ai (Compliance Access Key) atau Claude Console (kunci Admin API), dan konfirmasi bahwa kunci diaktifkan. Lihat Menyiapkan Compliance API.



403 Forbidden

Kunci di x-api-key valid tetapi tidak membawa scope yang dibutuhkan endpoint. Pesan verbatim mencantumkan scope yang dibawa kunci (Got:) dan scope yang dibutuhkan endpoint (Needed:), sehingga Anda dapat mengonfirmasi apa yang dibawa kunci tanpa memeriksa ulang Claude Console atau claude.ai. Scope Compliance Access Key tidak dapat diubah setelah pembuatan, sehingga setiap perbaikan scope yang tidak mencukupi mengarahkan Anda untuk membuat kunci baru alih-alih mengedit yang sudah ada.



Scope tidak mencukupi: Activity Feed

Type: permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['read:compliance_activities']

Penyebab: Kunci tanpa read:compliance_activities digunakan untuk memanggil GET /v1/compliance/activities. Ada dua jalur umum menuju error ini:

• Compliance Access Key (sk-ant-api01-...) dibuat tanpa scope read:compliance_activities.
• Kunci Admin API Claude Console (sk-ant-admin01-...) dibuat sebelum Compliance API diaktifkan untuk organisasi. Kunci yang dibuat sebelum pengaktifan tidak membawa scope tersebut; lihat Menyiapkan Compliance API.

Perbaikan: Scope Compliance Access Key tidak dapat diubah setelah pembuatan. Buat kunci baru yang menyertakan read:compliance_activities, atau gunakan kunci Admin API Claude Console. Lihat Kunci mana yang Anda butuhkan? untuk kondisi di mana kunci Admin API membawa scope ini.



Scope tidak mencukupi: data organisasi

Type: permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['read:compliance_org_data']

Penyebab: Kunci tanpa read:compliance_org_data digunakan untuk memanggil endpoint organizations, roles, groups, atau effective-settings. Ada dua jalur umum menuju error ini:

• Compliance Access Key (sk-ant-api01-...) dibuat tanpa scope read:compliance_org_data.
• Kunci Admin API Claude Console (sk-ant-admin01-...) digunakan. Kunci Admin API hanya membawa read:compliance_activities dan tidak dapat membaca metadata organisasi.

Perbaikan: Buat Compliance Access Key baru dengan read:compliance_org_data dipilih. Kunci Admin API tidak dapat membaca metadata organisasi; Compliance Access Key diperlukan.



Scope yang sudah dipensiunkan: pengaturan organisasi

Type: permission_error

Missing required scopes. Got: ['read:compliance_org_settings'] Needed: ['read:compliance_org_data']

Penyebab: Scope read:compliance_org_settings dipensiunkan pada 30 Juni 2026. GET /v1/compliance/organizations/{organization_id}/settings sekarang memerlukan read:compliance_org_data, scope yang sama dengan endpoint organisasi lainnya, dan scope yang dipensiunkan tidak lagi mengotorisasi apa pun. Compliance Access Key yang hanya membawa read:compliance_org_settings mengembalikan error ini pada setiap panggilan ke endpoint settings, meskipun kunci tersebut berfungsi sebelum pemensiunan. Scope yang dipensiunkan tidak lagi dapat dipilih atau diberikan saat membuat kunci.

Perbaikan: Scope Compliance Access Key tidak dapat diubah setelah pembuatan. Buat Compliance Access Key baru dengan read:compliance_org_data dipilih, perbarui integrasi Anda untuk menggunakannya, lalu hapus kunci lama. Kunci yang sudah membawa read:compliance_org_data tidak terpengaruh oleh pemensiunan ini.



Scope tidak mencukupi: data pengguna

Type: permission_error

Missing required scopes. Got: ['read:compliance_activities'] Needed: ['read:compliance_user_data']

Penyebab: Kunci tanpa read:compliance_user_data digunakan untuk memanggil endpoint chats, messages, files, projects, organization users, atau group-members. Ada dua jalur umum menuju error ini:

• Compliance Access Key (sk-ant-api01-...) dibuat tanpa scope read:compliance_user_data.
• Kunci Admin API Claude Console (sk-ant-admin01-...) digunakan. Kunci Admin API hanya membawa read:compliance_activities dan tidak dapat diberikan read:compliance_user_data, sehingga tidak dapat memanggil endpoint chat, file, project, project attachment, user, atau group-member.

Perbaikan: Gunakan Compliance Access Key yang dibuat di claude.ai dengan read:compliance_user_data dipilih. Jika permintaan memang seharusnya hanya untuk Activity Feed, arahkan kunci Admin API ke GET /v1/compliance/activities sebagai gantinya.



Scope tidak mencukupi: delete

Type: permission_error

Missing required scopes. Got: ['read:compliance_user_data'] Needed: ['delete:compliance_user_data']

Penyebab: Compliance Access Key tanpa delete:compliance_user_data digunakan untuk memanggil endpoint DELETE pada chats, files, atau projects.

Perbaikan: Buat Compliance Access Key baru dengan delete:compliance_user_data dipilih. Scope delete terpisah dari read:compliance_user_data sehingga kunci audit read-only tidak dapat menghapus konten.



404 Not Found

Endpoint berhasil diresolusi tetapi ID resource tidak ada atau sudah dihapus. Penghapusan Compliance API bersifat langsung dan permanen, sehingga 404 pada ID yang sebelumnya dikenal biasanya berarti konten telah dihapus permanen melalui panggilan delete Compliance API atau dihapus oleh kebijakan retensi. String tipe aktivitas yang dikutip dalam setiap Perbaikan (misalnya, claude_chat_created) adalah nilai yang dapat Anda teruskan ke filter activity_types[] Activity Feed; lihat Query aktivitas compliance untuk setiap nilai yang didukung.



Chat tidak ditemukan

Type: not_found_error

Chat claude_chat_01H5CWunD7RpVJ5bHa8RCkja not found.

Penyebab: ID chat di path tidak cocok dengan chat yang dapat dibaca melalui Compliance API. Chat mungkin telah dihapus permanen melalui panggilan Compliance API sebelumnya atau dihapus oleh kebijakan retensi organisasi Anda, atau mungkin milik organisasi yang tidak dapat dibaca oleh kunci pemanggil. Chat yang dihapus secara soft-delete oleh pengguna di claude.ai tidak mengembalikan 404; chat tersebut tetap dapat dibaca dengan deleted_at terisi.

Perbaikan: Konfirmasi ID chat terhadap aktivitas claude_chat_created atau claude_chat_viewed terbaru. Jika aktivitas tersebut baru dan pembacaan masih gagal, chat telah dihapus permanen (melalui API ini atau karena kedaluwarsa kebijakan retensi) atau milik organisasi di luar scope kunci Anda.



File tidak ditemukan

Type: not_found_error

No file found with provided id, or it has already been deleted.

Penyebab: ID file tidak ada atau telah dihapus. Error ini berlaku untuk file yang dilampirkan ke chat (claude_file_...) maupun file proyek.

Perbaikan: Rekonsiliasi terhadap aktivitas claude_file_uploaded atau claude_file_deleted terbaru. Jika file telah dihapus, binary-nya sudah hilang; catatan aktivitas tetap ada di feed selama jendela retensi 6 tahun.



Proyek tidak ditemukan

Type: not_found_error

No project is found with the provided id.

Penyebab: ID proyek tidak ada atau telah dihapus.

Perbaikan: Rekonsiliasi terhadap aktivitas claude_project_created atau claude_project_deleted terbaru. Activity Feed terus mengekspos event siklus hidup proyek bahkan setelah proyek itu sendiri hilang.



Dokumen proyek tidak ditemukan

Type: not_found_error

No project document found with provided id, or it has already been deleted.

Penyebab: ID dokumen proyek tidak ada atau telah dihapus. Error ini berlaku untuk dokumen proyek teks (claude_proj_doc_...), bukan untuk file proyek.

Perbaikan: Gunakan GET /v1/compliance/apps/projects/{project_id}/attachments untuk mencantumkan lampiran saat ini. Jika dokumen tidak ada, dokumen tersebut telah dihapus; ambil melalui catatan aktivitas claude_project_document_uploaded jika Anda hanya membutuhkan metadata-nya.



Organisasi, role, atau grup tidak ditemukan

Type: not_found_error

The "ce86b5f3-7c16-48b3-a9f3-e1d2c4b8a0f1" organization does not exist or the requester is not authorized to access it.

Endpoint organisasi, role, dan grup mengembalikan 404 not_found_error dalam format error standar. Pesan organisasi menyebutkan org_uuid; pesan role dan grup bersifat generik (Role not found., Group not found.). Ini terjadi ketika ID path (org_uuid, role_id, atau group_id) tidak ada atau tidak lagi termasuk dalam tree yang dapat dibaca oleh kunci pemanggil.

Penyebab: ID di path tidak cocok dengan catatan yang dapat dibaca melalui Compliance API. Role dan grup dapat dihapus, dan organisasi dapat dilepaskan dari tree induk.

Perbaikan: Verifikasi ID terhadap endpoint list yang sesuai, dan rekonsiliasi terhadap aktivitas organisasi, role, atau grup terbaru di Activity Feed.



Pengaturan organisasi tidak tersedia

Type: not_found_error

organization `91012d09-e48b-438e-a489-1bebfd8fa6f9` not found in this organization's hierarchy

Penyebab: GET /v1/compliance/organizations/{organization_id}/settings mengembalikan 404 ini dalam tiga kasus yang sengaja berbagi body yang sama agar respons tidak mengungkapkan apakah suatu organisasi ada: organization_id bukan salah satu organisasi yang tertaut dengan induk Anda, nilainya bukan UUID yang valid, atau endpoint settings belum diaktifkan untuk organisasi induk Anda.

Perbaikan: Verifikasi ID terhadap List organizations. Jika ID organisasi yang diketahui valid masih mengembalikan 404, endpoint settings belum diaktifkan untuk organisasi induk Anda; hubungi perwakilan Anthropic Anda.



409 Conflict

Permintaan terbentuk dengan baik dan terotorisasi tetapi bertentangan dengan status resource saat ini.



Proyek memiliki chat yang terlampir

Type: conflict_error

The "claude_proj_01KGp4eZNug9ri4kE35RSppq" project cannot be deleted as it has chats attached to it. Delete or detach all chats, and try deleting the project again.

Penyebab: DELETE /v1/compliance/apps/projects/{project_id} dipanggil pada proyek yang masih memiliki chat terlampir.

Perbaikan: Cantumkan chat proyek dengan GET /v1/compliance/apps/chats?user_ids[]={user_id}&project_ids[]={project_id} (filter project_ids[] memerlukan setidaknya satu nilai user_ids[]; enumerasi ID melalui List organization users), hapus masing-masing dengan DELETE /v1/compliance/apps/chats/{claude_chat_id}, lalu coba ulang penghapusan proyek.



429 Too Many Requests

Permintaan ke Compliance API dibatasi hingga 600 permintaan per menit per organisasi induk. Batas ini adalah satu anggaran tunggal yang dibagi di antara setiap kunci di bawah induk (Compliance Access Key dan kunci Admin API dari semua organisasi yang tertaut) dan di antara setiap endpoint /v1/compliance/*. Hubungi perwakilan Anthropic Anda jika integrasi Anda memerlukan batas yang lebih tinggi.

Setelah kunci API Anda terautentikasi, setiap respons Compliance API menyertakan header respons rate-limit standar sehingga klien Anda dapat melakukan throttling secara proaktif alih-alih menunggu 429:

• anthropic-ratelimit-requests-limit adalah anggaran permintaan per menit organisasi induk Anda.
• anthropic-ratelimit-requests-remaining adalah anggaran yang tersisa di jendela saat ini.
• anthropic-ratelimit-requests-reset adalah timestamp RFC 3339 ketika jendela direset dan anggaran penuh dipulihkan.

Respons 429 juga membawa header retry-after dengan jumlah detik yang harus ditunggu sebelum mengirim permintaan berikutnya. Nilai ini mungkin menyertakan margin keamanan kecil di luar anthropic-ratelimit-requests-reset; patuhi retry-after.

HTTP/1.1 429 Too Many Requests
date: Tue, 21 Apr 2026 14:38:02 GMT
retry-after: 25
anthropic-ratelimit-requests-limit: 600
anthropic-ratelimit-requests-remaining: 0
anthropic-ratelimit-requests-reset: 2026-04-21T14:38:25Z

{
  "error": {
    "type": "rate_limit_error",
    "message": "Compliance API rate limit of 600 requests per minute per parent organization has been exceeded. Retry after the time indicated by the retry-after header. Quote the request-id response header when contacting Anthropic support."
  }
}

Penyebab: Organisasi induk Anda mengirim lebih dari 600 permintaan ke /v1/compliance/* dalam jendela 1 menit, di seluruh kuncinya dan organisasi yang tertaut.

Perbaikan: Tunggu selama jumlah detik di header retry-after, lalu coba ulang. Jika header tidak ada (misalnya, dihapus oleh perantara), gunakan exponential backoff sebagai cadangan (mulai dari 1 detik, gandakan hingga 60 detik). Jangan majukan cursor paginasi Anda pada 429: permintaan yang gagal tidak mengembalikan data, sehingga cursor dari halaman terakhir yang berhasil masih benar.

Permintaan yang gagal autentikasi (kunci yang hilang atau tidak dikenali, atau kunci Claude API alih-alih Compliance Access Key atau kunci Admin API) ditolak sebelum rate limiter dan tidak mengonsumsi kuota. Kunci valid yang tidak memiliki scope yang dibutuhkan endpoint mengonsumsi satu unit kuota sebelum 403 dikembalikan.

Jika Anda melakukan polling Activity Feed secara terjadwal, anggarkan laju permintaan agregat Anda (di seluruh kunci, organisasi yang tertaut, dan worker yang berjalan bersamaan) di bawah batas organisasi induk. Pantau anthropic-ratelimit-requests-remaining untuk memperlambat sebelum Anda mencapainya. Lihat Merancang integrasi compliance Anda untuk memilih antara window-polling dan ingesti berbasis cursor.



500 Internal Server Error

Respons 500 dari Compliance API membawa header respons x-should-retry: false ketika kegagalan bersifat deterministik. SDK Anthropic mematuhi header ini secara otomatis. Jika Anda menggunakan library retry HTTP generik yang mencoba ulang pada setiap 5xx, tekan percobaan ulang ketika x-should-retry bernilai false; mencoba ulang error ini akan gagal dengan cara yang sama pada setiap percobaan.

Respons 500 tanpa header x-should-retry: false bersifat sementara: coba ulang dengan exponential backoff (mulai dari 1 detik, gandakan hingga 60 detik). Hal yang sama berlaku untuk respons 502, 503, 504, dan 529. Lihat Errors untuk semantik percobaan ulang di seluruh platform.

Untuk insiden di seluruh layanan, periksa status.anthropic.com.



Langkah selanjutnya