Um evento pode ser rejeitado por vários motivos. Por exemplo, o serviço de recebimento de eventos pode ficar temporariamente indisponível devido a uma interrupção, um erro pode ser encontrado pelo serviço ao processar um evento ou os recursos do serviço podem se esgotar. Erros temporários como esse podem ser repetidos.
Um evento também pode não ser entregue ao receptor de eventos. Por exemplo, o evento pode não corresponder ao esquema esperado configurado, ou a mediação do evento pode falhar antes que a mensagem do evento possa ser encaminhada para o destino final. Esses casos resultam em erros persistentes.
Erros transitórios
O Eventarc Advanced permite lidar com erros
temporários. Esses erros temporários podem ser repetidos e incluem aqueles com
os seguintes códigos de erro:
HTTP 408 Request Timeout
HTTP 409 Conflict
HTTP 429 Too Many Requests
HTTP 500 Internal Server Error
HTTP 502 Bad Gateway
HTTP 503 Service Unavailable
HTTP 504 Gateway Time-out
Erros persistentes
Ao contrário dos erros transitórios, os erros persistentes incluem:
Erros que ocorrem quando o número de novas tentativas configuradas é esgotado
Erros que ocorrem quando um evento falha antes de ser encaminhado para o destino
Erros que resultam em um código de erro considerado não passível de novas tentativas, por exemplo, códigos de erro diferentes dos listados para erros transitórios.
O Eventarc Advanced usa um atraso de espera exponencial para lidar com erros que podem ser repetidos. A política de novas tentativas padrão começa com um atraso de um segundo, que é dobrado após cada tentativa com falha (até um máximo de 60 segundos e cinco tentativas).
É possível mudar a política de nova tentativa padrão usando o console Google Cloud ou o comando
gcloud eventarc pipelines update.
Não é possível mudar o fator de espera padrão de 2.
Console
No Google Cloud console, acesse a página Eventarc>Pipelines.
Na página Editar pipeline, na seção Política de novas tentativas, modifique os seguintes campos:
Tentativas máximas: o número de novas tentativas. O padrão é 5 tentativas. Pode ser qualquer número real positivo. Se definido como 1, nenhuma política de repetição será aplicada e apenas uma tentativa de envio da mensagem será feita.
Atraso mínimo (segundos): o atraso inicial em segundos. O padrão é 1 segundo. Precisa estar entre 1 e 600.
Atraso máximo (segundos): o atraso máximo em segundos. O padrão é 60 segundos. Precisa estar entre 1 e 600.
Para configurar um backoff linear, defina os atrasos mínimo e máximo com o mesmo valor.
PIPELINE_NAME: o ID ou identificador totalmente qualificado do pipeline.
MIN_DELAY: o atraso inicial em segundos. O padrão é 1 segundo. Precisa estar entre 1 e 600.
MAX_DELAY: o atraso máximo em segundos. O padrão é 60 segundos. Precisa estar entre 1 e 600.
MAX_ATTEMPTS: o número de novas tentativas. O padrão é 5 tentativas. Pode ser qualquer número real positivo. Se definido como 1, nenhuma política de repetição será aplicada e apenas uma tentativa de envio da mensagem será feita.
O exemplo a seguir configura um espera linear definindo os atrasos mínimo e máximo com o mesmo valor:
Arquivar mensagens para lidar com erros persistentes
Você pode gravar mensagens em uma tabela do BigQuery conforme elas são recebidas. Isso permite identificar manualmente erros persistentes e lidar com eles de maneira adequada.
A seguir, apresentamos uma visão geral das etapas necessárias para arquivar as mensagens de evento, identificar erros persistentes e tentar novamente os eventos afetados.
Crie uma assinatura do BigQuery para
o tópico do Pub/Sub. Uma assinatura do BigQuery é um tipo de assinatura de exportação que grava mensagens em uma tabela do BigQuery conforme elas são recebidas. Como alternativa, é possível
criar a tabela ao criar a assinatura do BigQuery.
Crie um pipeline e uma inscrição
que encaminhe todas as mensagens recebidas pelo barramento (usando --cel-match="true") para
o tópico do Pub/Sub. Configure uma política de novas tentativas para o pipeline.
Por exemplo, os comandos a seguir criam um pipeline e uma inscrição:
Agora você tem dois conjuntos de dados separados do BigQuery: um que
armazena todas as mensagens recebidas pelo barramento avançado do Eventarc e outro
que armazena os registros do pipeline.
Para identificar mensagens com falha, use uma
instrução de consulta para unir
os dois conjuntos de dados do BigQuery no campo message_uid.
Os manipuladores de eventos que podem ser repetidos precisam ser idempotentes. Para isso,
siga as seguintes diretrizes gerais:
Muitas APIs externas permitem o fornecimento de uma chave de idempotência como um parâmetro. Se você
estiver usando uma API como essa, utilize a origem e o ID do evento como a
chave de idempotência. Os produtores precisam garantir que source + id seja exclusivo para cada evento diferente.
Além disso, você pode usar um atributo do CloudEvents, xgooglemessageuid, para
fornecer idempotência. O valor desse atributo é igual ao campo message_uid nas mensagens avançadas do Eventarc. Ele identifica de forma exclusiva a ação de publicar um evento. Por exemplo, se o mesmo evento
for publicado duas vezes em um barramento, cada evento terá um valor de
xgooglemessageuid diferente quando enviado a um manipulador de eventos.
A idempotência funciona bem com a entrega do tipo "pelo menos uma vez",
porque torna as novas tentativas mais seguras. Dessa forma, para escrever um código confiável, a prática recomendada é combinar idempotência com tentativas.
Verifique se o código é idempotente internamente. Por exemplo:
Garanta que mutações possam ocorrer mais de uma vez sem alterar o
resultado.
Consulte o estado do banco de dados em uma transação antes de alterar o estado.
Certifique-se de que todos os efeitos colaterais sejam idempotentes.
Execute uma verificação transacional fora do serviço, independente do código.
Por exemplo, mantenha a persistência de estado em algum local e registre que um determinado código de evento já foi processado.
Lide com chamadas duplicadas fora da banda. Por exemplo, tenha um processo de limpeza
separado que seja executado após chamadas duplicadas.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[[["\u003cp\u003eEventarc Advanced handles transient errors, such as temporary service unavailability, by automatically retrying them using an exponential backoff delay, with default settings of up to 5 attempts and a maximum 60-second delay, starting from a 1-second delay.\u003c/p\u003e\n"],["\u003cp\u003ePersistent errors, including those where retries are exhausted or events fail before routing, require manual identification and handling, and these errors can be found through error codes that are considered non-retryable.\u003c/p\u003e\n"],["\u003cp\u003eUsers can customize the retry policy for transient errors in Eventarc Advanced by adjusting the maximum attempts, minimum delay, and maximum delay through the Google Cloud console or the gcloud command-line tool.\u003c/p\u003e\n"],["\u003cp\u003eTo manage persistent errors, Eventarc Advanced allows for the archiving of event messages to a BigQuery table, where users can then identify and re-publish failed messages using the Eventarc Publishing API.\u003c/p\u003e\n"],["\u003cp\u003eEvent handlers should be designed to be idempotent, ensuring that multiple executions of the same event do not lead to unintended changes, often achievable through the use of idempotency keys or attributes like \u003ccode\u003exgooglemessageuid\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Retry events\n\n[Advanced](/eventarc/advanced/docs/overview)\n\nAn event can be rejected for multiple reasons. For example, the event receiver\nservice might be temporarily unavailable due to an outage; an error might be\nencountered by the service when processing an event; or service resources\nmight become exhausted. *Transient errors* like this can be retried.\n\nAn event can also fail to be delivered to the event receiver. For example, the\nevent might not match the expected schema that is configured, or the mediation\nof the event might fail before the event message can be routed to its final\ndestination. Such cases result in *persistent errors*.\n\nTransient errors\n----------------\n\nEventarc Advanced provides you with the capability to handle\ntransient errors. These transient errors can be retried and include those with\nthe following error codes:\n\n- HTTP `408 Request Timeout`\n- HTTP `409 Conflict`\n- HTTP `429 Too Many Requests`\n- HTTP `500 Internal Server Error`\n- HTTP `502 Bad Gateway`\n- HTTP `503 Service Unavailable`\n- HTTP `504 Gateway Time-out`\n\nPersistent errors\n-----------------\n\nIn contrast to transient errors, persistent errors include the following:\n\n- Errors that occur when the number of configured retries is exhausted\n- Errors that occur when an event fails before it can be routed to its destination\n- Errors that result in an error code that is considered non-retryable; for example, error codes other than those listed for transient errors\n\nYou can [manually identify persistent errors and handle them](#handle-persistent)\nappropriately.\n\nRetry transient errors\n----------------------\n\nEventarc Advanced uses an exponential backoff delay to handle\nerrors that can be retried. The default retry policy starts with a one-second\ndelay, and the delay is doubled after each failed attempt (up to a maximum of 60\nseconds and five attempts).\n\nYou can change the default retry policy using the Google Cloud console or the\n[`gcloud eventarc pipelines update`](/sdk/gcloud/reference/eventarc/pipelines/update)\ncommand.\n\nNote that the default backoff factor of `2` can't be changed. \n\n### Console\n\n1. In the Google Cloud console, go to the **Eventarc**\n \\\u003e **Pipelines** page.\n\n\n [Go to Pipelines](https://console.cloud.google.com/eventarc/pipelines)\n\n \u003cbr /\u003e\n\n2. Click the name of the pipeline.\n\n3. In the **Pipeline details** page, click **Edit**.\n\n4. On the **Edit pipeline** page, in the **Retry policy** section, modify\n the following fields:\n\n - **Max attempts** : the number of retries; default is `5` attempts. Can be any positive real number. If set to `1`, no retry policy is applied and only one attempt is made to deliver a message.\n - **Min delay (seconds)** : the initial delay in seconds; default is `1` second. Must be between `1` and `600`.\n - **Max delay (seconds)** : the maximum delay in seconds; default is `60` seconds. Must be between `1` and `600`.\n\n You can configure a linear backoff by setting the minimum and maximum\n delays to the same value.\n5. Click **Save**.\n\n### gcloud\n\n gcloud eventarc pipelines update \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e \\\n --min-retry-delay=\u003cvar translate=\"no\"\u003eMIN_DELAY\u003c/var\u003e \\\n --max-retry-delay=\u003cvar translate=\"no\"\u003eMAX_DELAY\u003c/var\u003e \\\n --max-retry-attempts=\u003cvar translate=\"no\"\u003eMAX_ATTEMPTS\u003c/var\u003e\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePIPELINE_NAME\u003c/var\u003e: the ID or fully qualified identifier of the pipeline.\n- \u003cvar translate=\"no\"\u003eMIN_DELAY\u003c/var\u003e: the initial delay in seconds; default is `1` second. Must be between `1` and `600`.\n- \u003cvar translate=\"no\"\u003eMAX_DELAY\u003c/var\u003e: the maximum delay in seconds; default is `60` seconds. Must be between `1` and `600`.\n- \u003cvar translate=\"no\"\u003eMAX_ATTEMPTS\u003c/var\u003e: the number of retries; default is `5` attempts. Can be any positive real number. If set to `1`, no retry policy is applied and only one attempt is made to deliver a message.\n\nThe following example configures a linear backoff by setting the minimum and\nmaximum delays to the same value: \n\n gcloud eventarc pipelines update my-pipeline \\\n --min-retry-delay=4 \\\n --max-retry-delay=4 \\\n --max-retry-attempts=5\n\nArchive messages to handle persistent errors\n--------------------------------------------\n\nYou can write messages to a BigQuery table as they are received. This\nlets you manually identify persistent errors and handle them appropriately.\n\nThe following provides an overview of the steps required to archive your event\nmessages, identify persistent errors, and retry the affected events.\n\n1. [Create a bus](/eventarc/advanced/docs/publish-events/create-bus). Configure the bus appropriately; for example, to [publish events from Google sources](/eventarc/advanced/docs/publish-events/publish-events-google-sources).\n2. [Create a Pub/Sub topic](/pubsub/docs/create-topic). This Pub/Sub topic will be the target destination for your pipeline.\n3. [Create a BigQuery subscription](/pubsub/docs/bigquery) for the Pub/Sub topic. A BigQuery subscription is a type of export subscription that writes messages to an existing BigQuery table as they are received. Alternatively, you can create the table when you create the BigQuery subscription.\n4. [Create a pipeline and enrollment](/eventarc/advanced/docs/receive-events/create-enrollment)\n that routes every message received by the bus (using `--cel-match=\"true\"`) to\n the Pub/Sub topic. Configure a retry policy for the pipeline.\n\n For example, the following commands create a pipeline and an enrollment: \n\n gcloud eventarc pipelines create my-archive-pipeline \\\n --destinations=pubsub_topic='my-archive-topic' \\\n --min-retry-delay=1 \\\n --max-retry-delay=20 \\\n --max-retry-attempts=6 \\\n --location=us-central1\n\n gcloud eventarc enrollments create my-archive-enrollment \\\n --cel-match=\"true\" \\\n --destination-pipeline=my-archive-pipeline \\\n --message-bus=my-message-bus \\\n --message-bus-project=my-google-cloud-project \\\n --location=us-central1\n\n5. [Route your pipeline logs](/logging/docs/export/configure_export_v2) to\n another BigQuery dataset.\n\n You should now have two separate BigQuery datasets: one that\n stores every message received by your Eventarc Advanced bus and one\n that stores your pipeline logs.\n6. To identify messages that have failed, use a\n [query statement to join](/bigquery/docs/reference/standard-sql/query-syntax#join_types)\n both BigQuery datasets on the `message_uid` field.\n\n7. After identifying any failed messages, you can publish them to your bus again\n using the [Eventarc Publishing API](/eventarc/docs/reference/publishing/rest).\n For example, you can\n [deploy a Cloud Run service or job](/run/docs/overview/what-is-cloud-run)\n to read the messages from BigQuery and\n [publish them directly](/eventarc/advanced/docs/publish-events/publish-events-direct-format)\n to the Eventarc Advanced bus.\n\nMake event handlers idempotent\n------------------------------\n\nEvent handlers that can be retried should be idempotent, using the following\ngeneral guidelines:\n\n- Many external APIs let you supply an idempotency key as a parameter. If you are using such an API, you should use the event source and ID as the idempotency key. (Producers must ensure that [source + id](/eventarc/advanced/docs/receive-events/use-cel#attributes) is unique for each distinct event.)\n- Additionally, you can use a CloudEvents attribute, `xgooglemessageuid`, to provide idempotency. The value of this attribute is the same as the `message_uid` field in Eventarc Advanced messages. It uniquely identifies the action of publishing an event. For example, if the same event is published twice to a bus, each event will have a different `xgooglemessageuid` value when sent to an event handler.\n- Idempotency works well with at-least-once delivery, because it makes it safe to retry. So a general best practice for writing reliable code is to combine idempotency with retries.\n- Make sure that your code is internally idempotent. For example:\n - Make sure that mutations can happen more than once without changing the outcome.\n - Query database state in a transaction before mutating the state.\n - Make sure that all side effects are themselves idempotent.\n- Impose a transactional check outside your service, independent of the code. For example, persist state somewhere recording that a given event ID has already been processed.\n- Deal with duplicate calls out-of-band. For example, have a separate clean up process that cleans up after duplicate calls.\n\nWhat's next\n-----------\n\n- [Troubleshoot issues](/eventarc/advanced/docs/troubleshoot)\n- [View audit logs](/eventarc/advanced/docs/audit-logs)"]]
