Memahami error API

Panduan ini menjelaskan cara Data Manager API menangani dan mengomunikasikan error. Memahami struktur dan arti error API sangat penting untuk membangun aplikasi yang tangguh yang dapat menangani masalah dengan baik, mulai dari input yang tidak valid hingga ketidaktersediaan layanan sementara.

Data Manager API mengikuti model error Google API standar, yang didasarkan pada Kode status gRPC. Setiap respons API yang menghasilkan error menyertakan objek Status dengan:

• Kode error numerik.
• Pesan error.
• Detail error tambahan opsional.

Kode error kanonis

Data Manager API menggunakan serangkaian kode error kanonis yang ditentukan oleh gRPC dan HTTP. Kode ini memberikan indikasi tingkat tinggi tentang jenis error. Anda harus selalu memeriksa kode ini terlebih dahulu untuk memahami sifat dasar masalahnya.

Untuk mengetahui detail selengkapnya tentang kode ini, lihat Panduan Desain API - Kode error.

Model gagal cepat

Data Manager API menggunakan model fast-fail. Jika permintaan berisi error struktural atau jika ada data yang gagal divalidasi untuk kolom wajib diisi, seluruh permintaan akan gagal, dan API tidak akan memproses data apa pun dalam permintaan tersebut.

Poin Penting: Model fast-fail melakukan serangkaian pemeriksaan validasi terbatas untuk mengidentifikasi masalah dasar yang akan sepenuhnya mencegah pemrosesan data lebih lanjut. Kegagalan validasi untuk kolom opsional tidak menyebabkan permintaan gagal. Data Manager API juga melakukan validasi yang lebih kompleks secara asinkron selama pemrosesan, dan melaporkan peringatan atau error dalam diagnostik.

Perbandingan dengan model kegagalan parsial

Model gagal cepat berbeda dengan model kegagalan parsial di beberapa Google API lainnya, seperti Google Ads API dan Campaign Manager 360 API. Dalam model kegagalan parsial, permintaan berhasil meskipun beberapa data mengalami error, dan respons berisi detail error untuk data yang gagal.

Meskipun kegagalan parsial dapat memudahkan, hal ini memiliki risiko yang signifikan karena model kegagalan parsial tidak secara proaktif memberi tahu Anda tentang error—Anda harus secara eksplisit memeriksa error di setiap respons. Hal ini dapat menyamarkan masalah penting karena permintaan berhasil meskipun API menolak banyak atau bahkan semua data dalam permintaan. Jika sebagian besar data dalam permintaan mengalami error, tetapi Anda tidak memeriksa responsnya, Anda mungkin sama sekali tidak menyadari masalah yang meluas pada data Anda, dan baru menemukan masalah tersebut beberapa hari atau minggu kemudian saat hasil kumulatif tidak sesuai dengan ekspektasi Anda.

Model fast-fail menghindari masalah ini dengan segera memberi tahu Anda tentang masalah pada data atau integrasi, sehingga Anda dapat mengambil tindakan yang sesuai.

Memeriksa error fast-fail dengan validateOnly

Sebagian besar permintaan penyerapan dan permintaan penghapusan mendukung kolom validateOnly. Saat Anda menetapkan validateOnly ke true, Data Manager API akan menjalankan pemeriksaan validasi dasar yang sama seperti untuk permintaan reguler, tetapi tidak menyerap atau menghapus data apa pun.

• Jika permintaan mengalami error, permintaan tersebut akan gagal dengan respons error yang sama seperti yang Anda dapatkan dari permintaan reguler.
• Jika permintaan lulus validasi, permintaan akan berhasil. Responsnya mencakup fieldWarnings untuk kolom opsional, seperti permintaan biasa.

Gunakan validateOnly untuk:

• Uji integrasi baru atau yang diperbarui tanpa memengaruhi data aktif Anda.
• Konfirmasi bahwa perbaikan menyelesaikan error sebelum Anda mengirim ulang permintaan.

Catatan: Permintaan khusus validasi yang berhasil mengonfirmasi bahwa permintaan tersebut lulus pemeriksaan validasi awal. Metode ini tidak memberi tahu Anda jika akan ada error selama pemrosesan asinkron. Error ini dilaporkan dalam diagnostik setelah data diserap. Anda tidak dapat mengambil diagnostik untuk permintaan yang menetapkan validateOnly ke true.

Menangani error

Ikuti langkah-langkah berikut jika permintaan gagal:

1. Periksa kode error untuk menemukan jenis error.

   • Jika Anda menggunakan gRPC, kode error ada di kolom code pada Status. Jika Anda menggunakan library klien, library tersebut dapat menampilkan jenis pengecualian tertentu yang sesuai dengan kode error. Misalnya, library klien untuk Java menampilkan com.google.api.gax.rpc.InvalidArgumentException jika kode errornya adalah INVALID_ARGUMENT.
   • Jika Anda menggunakan REST, kode error ada dalam respons error di error.status, dan status HTTP yang sesuai ada di error.code.
   Penting: Data Manager API menggunakan model fast-fail. Jika permintaan gagal, tidak ada data yang diproses. Perbaiki error dan kirim ulang seluruh permintaan.

2. Periksa payload detail standar untuk kode error. Payload detail standar adalah kumpulan pesan untuk error dari Google API. Error ini memberi Anda detail error dengan cara yang terstruktur dan konsisten. Setiap error dari Data Manager API mungkin memiliki beberapa pesan payload detail standar. Library klien Data Manager API memiliki metode bantuan untuk mendapatkan payload detail standar dari error.

   Apa pun kode errornya, sebaiknya Anda memeriksa dan mencatat payload ErrorInfo, RequestInfo, Help, dan LocalizedMessage.

   • ErrorInfo memiliki informasi yang mungkin tidak ada dalam payload lain.
   • RequestInfo memiliki ID permintaan, yang berguna jika Anda perlu menghubungi dukungan.
   • Help dan LocalizedMessage berisi link dan detail lainnya untuk membantu Anda mengatasi error.

   Selain itu, payload BadRequest berguna untuk error INVALID_ARGUMENT karena memberikan informasi tentang kolom yang menyebabkan error.

Peringatan penyerapan

Data Manager API menerima permintaan penyerapan sebanyak mungkin. Jika Anda menyertakan data yang tidak diperlukan, kegagalan validasi untuk kolom tersebut tidak akan menyebabkan permintaan gagal. Misalnya, jika item keranjang tidak memiliki ID produk penjual, API akan memproses permintaan lainnya dan menampilkan peringatan.

Respons penyerapan yang berhasil (kode status HTTP 200) menyertakan peringatan ini dalam daftar fieldWarnings. Setiap entri adalah objek FieldWarning dengan kolom berikut:

field

Lokasi kolom dalam permintaan, dalam sintaksis jalur snake case.

Jika jalur mengarah ke item dalam daftar (kolom repeated), indeksnya akan ditampilkan dalam tanda kurung siku ([...]) setelah nama daftar.

Misalnya, events.events[0].cart_data.items[0].merchant_product_id mengidentifikasi peringatan terkait item pertama dalam data keranjang peristiwa pertama dalam permintaan.

description

Penjelasan mengapa nilai yang diberikan menyebabkan peringatan.

reason

Nilai enum WarningReason yang mengidentifikasi jenis peringatan.

Penting: Peringatan penyerapan tidak akan menyebabkan permintaan gagal. Anda harus memeriksa respons untuk fieldWarnings guna memahami apakah semua data yang Anda kirim telah diterima.

Contoh dengan FieldWarning

Berikut adalah contoh respons untuk permintaan penyerapan yang berhasil, yang berisi peringatan karena ID produk penjual tidak ada untuk salah satu item keranjang.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
  "fieldWarnings": [
    {
      "field": "events.events[0].cart_data.items[0].merchant_product_id",
      "description": "The merchant product ID is missing in the cart item.",
      "reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
    }
  ]
}

Payload detail standar

Payload detail standar yang paling umum untuk Data Manager API adalah:

• BadRequest
• RequestInfo
• ErrorInfo
• Help dan LocalizedMessage

BadRequest

Periksa payload BadRequest saat permintaan gagal dengan INVALID_ARGUMENT (kode status HTTP 400).

Pesan BadRequest menunjukkan bahwa permintaan memiliki kolom dengan nilai yang buruk, atau tidak memiliki nilai untuk kolom yang wajib diisi. Periksa daftar field_violations di BadRequest untuk menemukan kolom yang memiliki error. Setiap entri field_violations memiliki informasi untuk membantu Anda memperbaiki error:

field

Lokasi kolom dalam permintaan, dalam sintaksis jalur snake case.

Jika jalur mengarah ke item dalam daftar (kolom repeated), indeksnya akan ditampilkan dalam tanda kurung siku ([...]) setelah nama daftar.

Misalnya, destinations[0].operating_account.account_id adalah account_id di operating_account item pertama dalam daftar destinations.

description

Penjelasan mengapa nilai tersebut menyebabkan error.

reason

Enum ErrorReason, seperti INVALID_HEX_ENCODING atau INVALID_CURRENCY_CODE.

Contoh BadRequest

Berikut adalah contoh respons untuk error INVALID_ARGUMENT dengan pesan BadRequest. field_violations menunjukkan error adalah accountId yang bukan angka. Nilai field destinations[0].login_account.account_id menunjukkan accountId dengan pelanggaran kolom berada di login_account item pertama dalam daftar destinations.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "destinations[0].login_account.account_id",
            "description": "String is not a valid number.",
            "reason": "INVALID_NUMBER_FORMAT"
          }
        ]
      }
    ]
  }
}

Berikut adalah contoh respons lain dari error INVALID_ARGUMENT dengan pesan BadRequest. Dalam hal ini, daftar field_violations menampilkan dua error:

1. event pertama memiliki nilai yang tidak dienkode hex pada ID pengguna kedua peristiwa.

2. event kedua memiliki nilai yang tidak dienkode hex pada ID pengguna ketiga peristiwa.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers[1]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          },
          {
            "field": "events.events[1].user_data.user_identifiers[2]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

RequestInfo

Periksa payload RequestInfo setiap kali permintaan gagal. RequestInfo berisi request_id yang secara unik mengidentifikasi permintaan API Anda.

{
  "@type": "type.googleapis.com/google.rpc.RequestInfo",
  "requestId": "t-4490c640-dc5d-4c28-91c1-04a1cae0f49f"
}

Saat mencatat error ke dalam log atau menghubungi dukungan, pastikan untuk menyertakan ID permintaan untuk membantu mendiagnosis masalah.

ErrorInfo

Periksa pesan ErrorInfo untuk mengambil informasi tambahan yang mungkin tidak tercakup dalam payload detail standar lainnya. Payload ErrorInfo berisi peta metadata dengan informasi tentang error.

Misalnya, berikut adalah ErrorInfo untuk kegagalan PERMISSION_DENIED yang disebabkan oleh penggunaan kredensial untuk project Google Cloud yang tidak mengaktifkan Data Manager API. ErrorInfo memberikan informasi tambahan tentang error, seperti:

• Project yang terkait dengan permintaan, di bagian metadata.consumer.
• Nama layanan, di bagian metadata.serviceTitle.
• URL tempat layanan dapat diaktifkan, di bagian metadata.activationUrl.

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "service": "datamanager.googleapis.com",
          "containerInfo": "PROJECT_NUMBER",
          "serviceTitle": "Data Manager API",
          "activationUrl": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

Error kuota dan pembatasan kapasitas

Jika permintaan melebihi batas project, API akan menampilkan error RESOURCE_EXHAUSTED (kode status HTTP 429). Payload ErrorInfo memberikan detail tentang batas mana yang terlampaui dalam peta metadata-nya:

consumer

Project Google Cloud yang terkait dengan permintaan, yang diformat sebagai projects/PROJECT_NUMBER.

quota_limit

Nama batas kuota yang terlampaui, seperti IngestionMutateRequestsPerMinutePerProject atau IngestionMutateRequestsPerDayPerProject. Anda dapat menggunakan nilai ini untuk menentukan apakah aplikasi melampaui batas per menit atau batas harian. Untuk mengetahui daftar lengkap nama batas, lihat Batas project.

quota_location

Lokasi tempat kuota diterapkan. Untuk Data Manager API, nilainya selalu global.

quota_metric

Metrik yang terkait dengan batas, seperti datamanager.googleapis.com/ingestion_mutate_requests.

service

Nama layanan, datamanager.googleapis.com.

Berikut adalah contoh respons error RESOURCE_EXHAUSTED saat permintaan melebihi batas per menit untuk permintaan modifikasi penyerapan:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Ingestion mutate requests' and limit 'Ingestion mutate requests per minute' of service 'datamanager.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RATE_LIMIT_EXCEEDED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "quota_limit": "IngestionMutateRequestsPerMinutePerProject",
          "quota_location": "global",
          "quota_metric": "datamanager.googleapis.com/ingestion_mutate_requests",
          "service": "datamanager.googleapis.com"
        }
      }
    ]
  }
}

Help dan LocalizedMessage

Periksa payload Help dan LocalizedMessage untuk mendapatkan link ke dokumentasi dan pesan error yang dilokalkan yang membantu Anda memahami dan memperbaiki error.

Misalnya, berikut adalah Help dan LocalizedMessage untuk kegagalan PERMISSION_DENIED yang disebabkan oleh penggunaan kredensial untuk project Google Cloud yang tidak mengaktifkan Data Manager API. Payload Help menampilkan URL tempat layanan dapat diaktifkan, dan LocalizedMessage memiliki deskripsi error.

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry."
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "Google API Console API activation",
            "url": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

Detail error akses

Jika Anda menggunakan salah satu library klien, gunakan metode bantuan untuk mendapatkan payload detail standar.

.NET

try {
    // Send API request
}
catch (Grpc.Core.RpcException rpcException)
{
    Console.WriteLine($"Exception encountered: {rpcException.Message}");
    var statusDetails =
        Google.Api.Gax.Grpc.RpcExceptionExtensions.GetAllStatusDetails(
            rpcException
        );
    foreach (var detail in statusDetails)
    {
        if (detail is Google.Rpc.BadRequest)
        {
            Google.Rpc.BadRequest badRequest = (Google.Rpc.BadRequest)detail;
            foreach (
                BadRequest.Types.FieldViolation? fieldViolation in badRequest.FieldViolations
            )
            {
                // Access attributes such as fieldViolation!.Reason and fieldViolation!.Field
            }
        }
        else if (detail is Google.Rpc.RequestInfo)
        {
            Google.Rpc.RequestInfo requestInfo = (Google.Rpc.RequestInfo)detail;
            string requestId = requestInfo.RequestId;
            // Log the requestId...
        }
        else if (detail is Google.Rpc.ErrorInfo)
        {
            Google.Rpc.ErrorInfo errorInfo = (Google.Rpc.ErrorInfo)detail;
            // Log the errorInfo.Reason and errorInfo.Metadata...

            // If handling a rate limit error, check the exceeded quota limit:
            if (errorInfo.Reason == "RATE_LIMIT_EXCEEDED" &&
                errorInfo.Metadata.TryGetValue("quota_limit", out string quotaLimit))
            {
                // Inspect quotaLimit to determine whether it is a per-minute
                // or daily limit (for example,
                // IngestionMutateRequestsPerMinutePerProject).
            }

            // Log the details in the 'Metadata' map...
            foreach (
                KeyValuePair<String, String> metadataEntry in errorInfo.Metadata
            )
            {
                // Log the metadataEntry.Key and metadataEntry.Value...
            }
        }
        else
        {
            // ...
        }
    }
}

Java

try {
  // Send API request
} catch (com.google.api.gax.rpc.InvalidArgumentException invalidArgumentException) {
  // Gets the standard BadRequest payload from the exception.
  BadRequest badRequest = invalidArgumentException.getErrorDetails().getBadRequest();
  for (int i = 0; i < badRequest.getFieldViolationsCount(); i++) {
    FieldViolation fieldViolation = badRequest.getFieldViolations(i);
    // Access attributes such as fieldViolation.getField() and fieldViolation.getReason()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.

  // Gets the standard ErrorInfo payload from the exception.
  ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
  // Log the 'reason' and 'domain'...

  // If handling a rate limit error, check the exceeded quota limit:
  if (errorInfo != null && "RATE_LIMIT_EXCEEDED".equals(errorInfo.getReason())) {
    String quotaLimit = errorInfo.getMetadataMap().get("quota_limit");
    // Inspect quotaLimit to determine whether it is a per-minute
    // or daily limit (for example,
    // IngestionMutateRequestsPerMinutePerProject).
  }

  // Log the details in the 'metadata' map...
  for (Entry<String, String> metadataEntry : errorInfo.getMetadataMap().entrySet()) {
    // Log the metadataEntry key and value...
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = apiException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

Menangani error ukuran header untuk gRPC

Jika sejumlah besar data dalam permintaan penyerapan atau permintaan penghapusan gagal divalidasi, Data Manager API akan menampilkan semua error dalam payload BadRequest respons.

Di gRPC, layanan menampilkan detail error ini di header respons HTTP/2 (metadata). Secara default, library klien gRPC membatasi header masuk hingga ukuran maksimum (biasanya 8–10 KB). Jika detail error melebihi batas ini, transport HTTP/2 sisi klien akan gagal sebelum mengurai respons error, sehingga menampilkan pengecualian seperti:

Http2Exception: Header size exceeded max allowed size (10240)

Karena klien tidak dapat memproses header respons, klien akan membatalkan streaming (yang muncul sebagai status HTTP 499 Client Closed Request di log sisi server), dan aplikasi Anda tidak dapat mengakses detail error BadRequest.

Catatan: Masalah ini hanya memengaruhi permintaan gRPC. Permintaan REST tidak terpengaruh karena REST menampilkan detail error dalam isi respons, bukan header.

Untuk mengatasi masalah ini dan memeriksa daftar lengkap error, konfigurasikan klien gRPC Anda dengan ukuran metadata masuk maksimum yang ditingkatkan (seperti 16 MB):

.NET

// Creates a client for the ingestion service. Increases the maximum metadata size to
// 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain large error
// details.
IngestionServiceClient ingestionServiceClient = new IngestionServiceClientBuilder
{
    GrpcChannelOptions = GrpcChannelOptions.Empty.WithCustomOption(
        "grpc.max_metadata_size",
        16 * 1024 * 1024
    ),
}.Build();
IngestAudienceMembers.cs

Java

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
InstantiatingGrpcChannelProvider provider =
    IngestionServiceSettings.defaultGrpcTransportProviderBuilder()
        .setMaxInboundMetadataSize(16 * 1024 * 1024)
        .build();
IngestionServiceSettings settings =
    IngestionServiceSettings.newBuilder().setTransportChannelProvider(provider).build();
try (IngestionServiceClient ingestionServiceClient = IngestionServiceClient.create(settings)) {
  // ...
}
IngestAudienceMembers.java

Node

// Creates a client for the ingestion service. Increases the maximum metadata
// size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain
// large error details.
const client = new IngestionServiceClient({
  'grpc.max_metadata_size': 16 * 1024 * 1024,
});
ingest_audience_members.ts

PHP

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
$client = new IngestionServiceClient([
    'transportConfig' => [
        'grpc' => [
            'stubOpts' => [
                'grpc.max_metadata_size' => 16 * 1024 * 1024,
            ],
        ],
    ],
]);
ingest_audience_members.php

Python

# Creates a client for the ingestion service. Increases the maximum
# metadata size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses
# contain large error details.
channel = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport.create_channel(
    options=[("grpc.max_metadata_size", 16 * 1024 * 1024)]
)
transport = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport(
    channel=channel
)
client: datamanager_v1.IngestionServiceClient = (
    datamanager_v1.IngestionServiceClient(transport=transport)
)
ingest_audience_members.py

Praktik terbaik untuk penanganan error

Untuk membangun aplikasi yang tangguh, terapkan praktik terbaik berikut.

Memvalidasi sebelum mengirim

Saat Anda membuat atau mengubah integrasi, kirim permintaan dengan validateOnly ditetapkan ke true untuk menangkap error fast-fail sebelum Anda menyerap data.

Memeriksa detail error

Selalu cari salah satu payload detail standar seperti BadRequest. Setiap payload detail standar berisi informasi untuk membantu Anda memahami penyebab error.

Membedakan error klien dari error server

Tentukan apakah error disebabkan oleh masalah pada implementasi Anda (klien) atau masalah pada API (server).

• Error klien: Kode seperti INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Error ini memerlukan perubahan pada permintaan atau status/kredensial aplikasi Anda. Jangan mencoba lagi permintaan tanpa mengatasi masalahnya.
• Error server: Kode seperti UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Hal ini menunjukkan adanya masalah sementara pada layanan API.

Menerapkan strategi percobaan ulang

Tentukan apakah error dapat dicoba lagi, dan gunakan strategi percobaan ulang.

• Coba lagi hanya untuk error server sementara (seperti UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN, dan ABORTED) dan pembatasan kapasitas per menit (RESOURCE_EXHAUSTED dengan RATE_LIMIT_EXCEEDED).

• Untuk pembatasan kapasitas, periksa quota_limit di ErrorInfo:

  • Jika batasnya adalah per menit (seperti IngestionMutateRequestsPerMinutePerProject), jeda permintaan dan coba lagi menggunakan backoff eksponensial dengan jitter.

  • Jika batasnya adalah harian (seperti IngestionMutateRequestsPerDayPerProject), jangan langsung mencoba lagi. Jeda pemrosesan hingga kuota harian direset pada tengah malam Waktu Pasifik.

• Gunakan algoritma backoff eksponensial untuk menunggu periode yang meningkat di antara percobaan ulang. Hal ini membantu menghindari layanan yang sudah terbebani menjadi semakin kewalahan. Misalnya, tunggu 1 dtk, lalu 2 dtk, lalu 4 dtk, dan lanjutkan hingga jumlah maksimum percobaan ulang atau total waktu tunggu.

• Tambahkan sejumlah kecil "jitter" acak ke penundaan backoff untuk mencegah masalah "thundering herd" saat banyak klien mencoba lagi secara bersamaan.

Catat secara menyeluruh

Catat respons error lengkap, termasuk semua payload detail standar, terutama ID permintaan. Informasi ini penting untuk men-debug dan melaporkan masalah ke dukungan Google jika diperlukan.

Memberikan masukan pengguna

Berdasarkan kode dan pesan dalam payload detail standar, berikan masukan yang jelas dan bermanfaat kepada pengguna aplikasi Anda. Misalnya, daripada hanya "Terjadi error", Anda dapat mengatakan "ID transaksi tidak ada" atau "ID akun tujuan tidak ditemukan".

Dengan mengikuti panduan ini, Anda dapat mendiagnosis dan menangani error yang ditampilkan oleh Data Manager API secara efektif, sehingga menghasilkan aplikasi yang lebih stabil dan mudah digunakan.