A multilingual support notice says a payment event was ‘delivered exactly once’. In reality the producer may have published two distinct messages during retries, an ordered subscription may redeliver a later acknowledged message, and a worker may send the same email twice. Google Cloud Pub/Sub has useful delivery controls, but their names do not relieve writers of the obligation to say exactly which delivery layer they describe.
This guide explains Google Cloud Pub/Sub topics and subscriptions, message ordering keys, exactly-once delivery for pull subscriptions, acknowledgment deadlines, StreamingPull, dead-letter topics, replay with seek, snapshots and message retention. It is for global technical translation, localization of cloud documentation, system runbooks, data engineering guides and reader-friendly explanations of Pub/Sub semantics.
Our running example is a fictional learning platform that publishes synthetic course-registration updates to subscribers in multiple countries. We use no real user data. The aim is to make the difference between publish success, message delivery, subscriber acknowledgment and downstream business completion immediately clear. Feature availability, defaults and operational limits should always be checked against the current configured Google Cloud resources.
Quick answer: the promise has a boundary
Pub/Sub delivers messages from a topic to subscriptions, which maintain independent progress. The standard delivery model permits redelivery. Exactly-once delivery is a specialized feature supported for pull subscriptions within a cloud region, not a promise that a producer will publish a business event only once or that a subscriber will charge a card only once. Ordering is another independent option with per-key limits. A concise correct explanation tells readers which feature is configured and what it protects.
A fictional event with two independent subscriptions
A course-registration event E17 is accepted by Pub/Sub at 12:00 UTC. Subscription A drives a reporting service, while subscription B drives an email service. A acknowledges the delivery after writing a report; B’s worker fails before recording an acknowledgment. Both subscriptions can have validly different states for the same original message. An accurate localized dashboard says ‘reporting subscription acknowledged E17; email subscription remains unacknowledged’. The word delivered is too weak to carry this distinction without a qualifier.
How ordering can produce apparent duplicates
Suppose messages 1, 2 and 3 share ordering key student-42 and the subscription enables ordering. If message 2 is redelivered under documented conditions, Pub/Sub may redeliver subsequent same-key messages, including ones already acknowledged. That is part of maintaining ordered delivery behavior, not proof that the producer sent an entirely new event. Always compare server message IDs and application event IDs before telling a user that a second registration occurred.
Pub/Sub terminology, safe translations and the evidence needed
1. Pub/Sub topic
A Google Cloud Pub/Sub topic is the publishing destination for messages. Its messages can be delivered to multiple attached subscriptions, each with its own lifecycle and acknowledgment state.
What can go wrong: Do not call a topic itself a single worker queue. Better wording: “Publishers send messages to the named topic.”
Verify: Inspect the topic, project and associated subscriptions. Record the configuration and observation time in a multilingual incident log before making the claim public.
2. Subscription
A subscription defines how its consumers receive a topic’s messages and tracks delivery progress independently from other subscriptions.
What can go wrong: Do not imply one subscription’s acknowledgment handles every reader. Better wording: “Subscription A acknowledged this message; subscription B has separate state.”
Verify: Check subscription identity whenever reporting progress. Record the configuration and observation time in a multilingual incident log before making the claim public.
3. Publishing response
A successful publish request indicates acceptance by Pub/Sub under the service contract. It does not mean that a downstream job or human notification succeeded.
What can go wrong: Avoid calling publish success final business delivery. Better wording: “The service accepted the published message.”
Verify: Compare publish confirmation and consumer-side evidence. Record the configuration and observation time in a multilingual incident log before making the claim public.
4. Message ID
Pub/Sub assigns a message identifier on successful publication. Producer retries that generate distinct accepted publishes may result in distinct IDs for similar business content.
What can go wrong: Message ID is not automatically a permanent business idempotency key. Better wording: “This accepted publication received this message ID.”
Verify: Keep a separate application event ID for reconciliation. Record the configuration and observation time in a multilingual incident log before making the claim public.
5. Data payload
Message data is an application-defined byte payload. Pub/Sub transports it without guaranteeing that the business meaning has been validated by every subscriber.
What can go wrong: Do not call transport acceptance schema validation when no schema applies. Better wording: “The message carries this encoded application payload.”
Verify: Check format, encoding and validation stage. Record the configuration and observation time in a multilingual incident log before making the claim public.
6. Attributes
Attributes are named metadata fields used for routing, filters and application handling. Their keys and values may be case sensitive and operationally significant.
What can go wrong: Do not translate attribute keys inside a live configuration example. Better wording: “This message includes the stated metadata attributes.”
Verify: Preserve exact key names and inspect filter expressions. Record the configuration and observation time in a multilingual incident log before making the claim public.
7. Default delivery mode
Pub/Sub ordinarily uses at-least-once delivery behavior, so valid redelivery may occur when deadlines expire or acknowledgments do not complete.
What can go wrong: Do not promise a single delivery because normal traffic usually appears once. Better wording: “Subscribers must tolerate possible redelivery.”
Verify: Check subscription settings and acknowledgment logs. Record the configuration and observation time in a multilingual incident log before making the claim public.
8. No default ordering
Without explicit message ordering, consumers cannot assume business events arrive in their original publisher order. Separate keys also lack global order guarantees.
What can go wrong: Do not turn accidental observed order into a contractual promise. Better wording: “This subscription does not guarantee a total delivery order.”
Verify: Inspect enableMessageOrdering and event-key design. Record the configuration and observation time in a multilingual incident log before making the claim public.
9. Ordering key
An ordering key groups related messages for ordered delivery when appropriate settings and regional requirements are met. It is not the same thing as a fixed partition number.
What can go wrong: Do not translate an ordering key as a physical shard. Better wording: “Related messages use the same configured ordering key.”
Verify: Verify message keys and subscription ordering settings. Record the configuration and observation time in a multilingual incident log before making the claim public.
10. Same-region publishing
For an ordering key, messages must be published in the same region to meet the supported ordering conditions. Cross-region publishing is not one magic global sequence.
What can go wrong: Do not imply globally consistent ordering from one key string. Better wording: “These ordered publishes used the same region.”
Verify: Record regional endpoints and publisher behavior. Record the configuration and observation time in a multilingual incident log before making the claim public.
11. Within-key ordering
When properly enabled, ordered delivery applies to messages sharing a key. It does not order unrelated keys against one another.
What can go wrong: Do not translate per-key order as total topic order. Better wording: “Messages for key A are delivered in their relevant order.”
Verify: Test with at least two keys and note the observed scope. Record the configuration and observation time in a multilingual incident log before making the claim public.
12. Ordering-key redelivery
Redelivery of one ordered message can trigger redelivery of later messages with the same key, including previously acknowledged ones, under documented conditions.
What can go wrong: A repeated later message need not be a new business publication. Better wording: “A prior redelivery caused later same-key delivery to repeat.”
Verify: Compare original message IDs and order-key sequence. Record the configuration and observation time in a multilingual incident log before making the claim public.
13. Ordering throughput
An ordering key introduces per-key throughput and concurrency constraints even when a topic can handle much more traffic overall.
What can go wrong: Do not claim one hot key can use all aggregate topic capacity. Better wording: “This key’s ordered delivery is subject to its own limits.”
Verify: Inspect quotas, key distribution and subscription latency. Record the configuration and observation time in a multilingual incident log before making the claim public.
14. Publisher retry
Clients may retry after an ambiguous publishing error. Distinct successfully accepted publishes can represent the same intended business event.
What can go wrong: Do not call exactly-once subscriber delivery permanent producer deduplication. Better wording: “A retry may create a second accepted message.”
Verify: Correlate application event IDs across publish attempts. Record the configuration and observation time in a multilingual incident log before making the claim public.
15. Pull subscription
Pull subscribers request messages and acknowledge using acknowledgment identifiers. Pull consumption supports capabilities not available to push subscribers.
What can go wrong: Do not describe pull and push as identical confirmation models. Better wording: “This worker receives through a pull subscription.”
Verify: Check the subscription type and client API. Record the configuration and observation time in a multilingual incident log before making the claim public.
16. StreamingPull
StreamingPull provides a long-lived streaming exchange for pull subscribers, with flow control and acknowledgments managed through the supported client.
What can go wrong: A continuous stream is not permission to skip per-message completion handling. Better wording: “The client uses StreamingPull to receive and acknowledge messages.”
Verify: Inspect library configuration and acknowledgment responses. Record the configuration and observation time in a multilingual incident log before making the claim public.
17. Push subscription
Push delivery uses HTTP requests to a subscriber endpoint; successful responses indicate acknowledgment by that endpoint under the push model.
What can go wrong: An HTTP response does not prove every downstream database operation completed. Better wording: “The endpoint responded successfully to the push attempt.”
Verify: Check response codes and endpoint behavior. Record the configuration and observation time in a multilingual incident log before making the claim public.
18. Push authentication
Authenticated push requests can include credentials that the receiving endpoint must validate. Authentication is a separate concern from message semantics.
What can go wrong: Do not imply a known URL alone proves an authenticated sender. Better wording: “The endpoint verified the configured push identity.”
Verify: Check audience, issuer and authorization settings. Record the configuration and observation time in a multilingual incident log before making the claim public.
19. BigQuery subscription
An export subscription can write eligible messages into BigQuery under its own schema and delivery behavior. It is not the same as an application pull worker.
What can go wrong: Do not promise all pull-only features on an export subscription. Better wording: “This export subscription writes records to its destination.”
Verify: Inspect export settings and destination errors. Record the configuration and observation time in a multilingual incident log before making the claim public.
20. Cloud Storage subscription
A storage export subscription writes messages into objects according to configured output behavior. Object formation and timestamps differ from per-message business events.
What can go wrong: Do not treat an object file timestamp as every contained event’s timestamp. Better wording: “The export created a storage object containing messages.”
Verify: Inspect object format, partitioning and retention. Record the configuration and observation time in a multilingual incident log before making the claim public.
21. Acknowledgment ID
A delivery supplies an acknowledgment ID for confirming that specific delivery attempt. The ID is not identical to the stable Pub/Sub message ID.
What can go wrong: Do not reuse old ack IDs as permanent record identifiers. Better wording: “This delivery has its own acknowledgment ID.”
Verify: Keep message ID, delivery attempt and ack ID separate. Record the configuration and observation time in a multilingual incident log before making the claim public.
22. Acknowledge operation
An acknowledgment informs the service that processing has been completed according to the subscriber’s decision. It does not prove success in every external system.
What can go wrong: Do not call an ack a verified payment or email receipt. Better wording: “The subscriber acknowledged this message delivery.”
Verify: Check the relevant downstream transaction independently. Record the configuration and observation time in a multilingual incident log before making the claim public.
23. Ack deadline
The acknowledgment deadline bounds the interval in which the subscriber must acknowledge or extend processing. Expiry can make redelivery eligible.
What can go wrong: Do not call the ack deadline a guarantee of business completion time. Better wording: “The acknowledgment deadline elapsed before confirmation.”
Verify: Compare processing duration and configured deadline. Record the configuration and observation time in a multilingual incident log before making the claim public.
24. ModifyAckDeadline
Subscribers can adjust an outstanding delivery’s acknowledgment deadline. This supports longer processing but does not make external work permanent.
What can go wrong: A deadline extension is not successful completion. Better wording: “The client extended time to process this delivery.”
Verify: Check extension calls and eventual acknowledgment. Record the configuration and observation time in a multilingual incident log before making the claim public.
25. Nack behavior
Setting an acknowledgment deadline to zero or otherwise signaling inability to process can prompt redelivery under the service contract.
What can go wrong: Do not translate negative acknowledgment as permanent quarantine. Better wording: “The subscriber requested the message be made eligible for another attempt.”
Verify: Inspect retry settings and next delivery. Record the configuration and observation time in a multilingual incident log before making the claim public.
26. Valid redelivery
The same message ID can return after an expired deadline or explicit nack. This is expected at-least-once behavior rather than proof of a new publish.
What can go wrong: Do not count redeliveries as new business events. Better wording: “The same message was delivered again.”
Verify: Match IDs and observe ack-deadline history. Record the configuration and observation time in a multilingual incident log before making the claim public.
27. Duplicate delivery definition
Pub/Sub distinguishes valid redelivery from unexpected duplicate deliveries outside such conditions. Exactly-once controls address the subscription delivery side within its supported scope.
What can go wrong: Do not call all repeated observations a service defect. Better wording: “This occurrence meets the documented redelivery condition.”
Verify: Inspect acknowledgment success and outstanding deadlines. Record the configuration and observation time in a multilingual incident log before making the claim public.
28. Exactly-once delivery
Google Pub/Sub supports an exactly-once delivery feature for pull subscriptions within a cloud region, under stated acknowledgment requirements.
What can go wrong: Do not imply global exactly-once business side effects. Better wording: “This pull subscription uses the supported exactly-once delivery behavior.”
Verify: Verify subscription type, feature setting and regional conditions. Record the configuration and observation time in a multilingual incident log before making the claim public.
29. Pull-only scope
Push and export subscriptions do not support the pull-subscription exactly-once delivery feature in the same way.
What can go wrong: Do not present a push endpoint as eligible for this guarantee. Better wording: “The exactly-once feature applies to supported pull subscribers.”
Verify: Inspect subscription type before using the term. Record the configuration and observation time in a multilingual incident log before making the claim public.
30. Acknowledgment success response
With exactly-once enabled, clients can determine whether an acknowledgment succeeded. A successful ack changes redelivery guarantees within the documented scope.
What can go wrong: Do not equate an attempted ack with a confirmed ack. Better wording: “The client received confirmation that acknowledgment succeeded.”
Verify: Use client APIs that surface acknowledgment outcomes. Record the configuration and observation time in a multilingual incident log before making the claim public.
31. Stale acknowledgment IDs
After a later valid delivery, an old acknowledgment ID may no longer be accepted for the message under exactly-once behavior.
What can go wrong: Do not silently retry an expired ack ID forever. Better wording: “The previous acknowledgment ID was no longer valid.”
Verify: Inspect latest delivery and returned acknowledgment error. Record the configuration and observation time in a multilingual incident log before making the claim public.
32. Exactly-once performance tradeoff
Exactly-once features introduce operational and latency considerations that can matter to subscriber throughput and cost.
What can go wrong: Do not translate the label as an unconditional free improvement. Better wording: “The feature changes delivery semantics and performance characteristics.”
Verify: Measure actual latency under the chosen configuration. Record the configuration and observation time in a multilingual incident log before making the claim public.
33. External side effects
A successful Pub/Sub acknowledgment does not bind an independent database commit or email delivery into one transaction. Application idempotency remains necessary.
What can go wrong: Do not call exactly-once delivery exactly-once payment or notification. Better wording: “This message was acknowledged; external actions require separate proof.”
Verify: Use stable business keys in downstream operations. Record the configuration and observation time in a multilingual incident log before making the claim public.
34. Publisher-side duplicates
Producer retries can produce distinct accepted message IDs for the same intended event, even when a consumer uses exactly-once delivery semantics.
What can go wrong: Do not promise the feature eliminates all duplicate business content. Better wording: “Two accepted messages may describe one underlying action.”
Verify: Compare application event identifiers. Record the configuration and observation time in a multilingual incident log before making the claim public.
35. Subscription filters
Subscriptions can filter messages using attributes. Filters select which messages belong to the subscription’s delivery behavior, not whether a publisher created them.
What can go wrong: Do not translate a filtered-out message as a producer failure. Better wording: “The subscription filter excluded this message.”
Verify: Test attribute values against the exact filter expression. Record the configuration and observation time in a multilingual incident log before making the claim public.
36. Delivery attempts
A delivery-attempt count can describe how often Pub/Sub tried a message under supported dead-letter settings; counting details have documented limitations.
What can go wrong: Do not present attempt count as a perfect external processing ledger. Better wording: “The subscription recorded this delivery attempt count.”
Verify: Check whether dead-lettering and attempt tracking are enabled. Record the configuration and observation time in a multilingual incident log before making the claim public.
37. Dead-letter topic
A subscription can route repeatedly undeliverable messages to a dead-letter topic using configured policies and service permissions.
What can go wrong: Do not claim a dead-letter event was successfully resolved. Better wording: “The message was forwarded for separate failure handling.”
Verify: Inspect topic, subscription and IAM setup. Record the configuration and observation time in a multilingual incident log before making the claim public.
38. Dead-letter best effort
Dead-letter forwarding and maximum delivery attempts have best-effort behaviors, so a number should not be translated as a rigid guaranteed boundary in every case.
What can go wrong: Do not promise the message will be forwarded after exactly N tries. Better wording: “The policy targets forwarding after unsuccessful attempts.”
Verify: Review configuration and observed attempts. Record the configuration and observation time in a multilingual incident log before making the claim public.
39. Retry policy
Immediate retries and exponential-backoff retry policies influence when unacknowledged messages return, but actual delivery timing can vary.
What can go wrong: Do not translate backoff as a guaranteed fixed appointment time. Better wording: “The subscription retries eligible messages under its policy.”
Verify: Inspect retry settings and service observations. Record the configuration and observation time in a multilingual incident log before making the claim public.
40. Retention on subscriptions
Subscription message retention controls the availability of messages associated with the subscription according to settings. It must not be confused with topic retention.
What can go wrong: Do not treat one retention setting as the whole topic’s policy. Better wording: “This subscription retains eligible messages for its configured duration.”
Verify: Read subscription retention configuration. Record the configuration and observation time in a multilingual incident log before making the claim public.
41. Retain acknowledged messages
A setting can retain acknowledged messages for possible replay when configured. Acknowledgment alone does not universally mean immediate permanent unavailability.
What can go wrong: Do not promise that every ack erases the content. Better wording: “Acknowledged messages remain eligible for replay under this setting.”
Verify: Check retain-acked configuration and retention window. Record the configuration and observation time in a multilingual incident log before making the claim public.
42. Topic retention
Topic-level retention can preserve published messages independently of subscription-specific settings, subject to its documented limits.
What can go wrong: Do not infer that an unconfigured topic keeps history indefinitely. Better wording: “This topic retains messages under its stated policy.”
Verify: Check the topic retention setting. Record the configuration and observation time in a multilingual incident log before making the claim public.
43. Seek to timestamp
Seek can adjust a subscription’s delivery point to a past or future timestamp under supported constraints and available retention.
What can go wrong: Do not translate seek as restoration of expired history. Better wording: “The subscription seeks to a selected available time.”
Verify: Verify retention and expected redelivery effects. Record the configuration and observation time in a multilingual incident log before making the claim public.
44. Seek to snapshot
A subscription can seek to a saved snapshot of subscription state, subject to snapshot validity and supported operations.
What can go wrong: Do not describe a snapshot as a complete backup of every published payload forever. Better wording: “The subscription seeks to this valid snapshot.”
Verify: Check snapshot existence, expiration and related retention. Record the configuration and observation time in a multilingual incident log before making the claim public.
45. Snapshot lifetime
Snapshot expiration depends on backlog age and has a maximum possible lifetime of seven days under documented rules. It is not automatically a seven-day guarantee.
What can go wrong: Do not advertise every snapshot as usable for exactly seven days. Better wording: “Snapshot validity depends on its calculated expiration.”
Verify: Check oldest unacknowledged message age before creating one. Record the configuration and observation time in a multilingual incident log before making the claim public.
46. Subscription expiration
Subscription lifecycle and inactivity expiration policies are distinct from message retention, so a subscription may cease to exist despite topic activity.
What can go wrong: Do not use a message retention value as a subscription existence guarantee. Better wording: “The subscription has an independent expiration policy.”
Verify: Inspect subscription lifecycle settings. Record the configuration and observation time in a multilingual incident log before making the claim public.
47. Backlog
Backlog metrics refer to messages waiting for acknowledgment or processing according to the subscription’s measurement. They are not synonymous with total topic history.
What can go wrong: Do not call backlog a count of all published messages. Better wording: “This metric measures outstanding subscription work.”
Verify: Check metric definition and observation time. Record the configuration and observation time in a multilingual incident log before making the claim public.
48. Oldest unacked age
Age of the oldest unacknowledged message helps diagnose slow processing but does not directly tell you whether an external business result is correct.
What can go wrong: Do not translate this as latency of every user action. Better wording: “The oldest outstanding delivery has the reported age.”
Verify: Compare with processing logs and deadlines. Record the configuration and observation time in a multilingual incident log before making the claim public.
49. IAM roles
Cloud IAM permissions govern publisher, subscriber and administrative actions. A topic name alone does not grant a reader permission to consume messages.
What can go wrong: Do not equate knowing an endpoint with authorized access. Better wording: “This identity has the named Pub/Sub permissions.”
Verify: Inspect service accounts and resource policies. Record the configuration and observation time in a multilingual incident log before making the claim public.
50. Schema enforcement
Pub/Sub schemas can constrain accepted message formats in supported configurations, but validation behavior depends on schema type and settings.
What can go wrong: Do not claim every topic validates all business semantics. Better wording: “This topic uses the configured schema validation behavior.”
Verify: Inspect schema revisions and publisher encoding. Record the configuration and observation time in a multilingual incident log before making the claim public.
51. Schema evolution
Changing fields across versions can affect consumers reading retained messages. Translation must preserve exact field names, optionality and backward-compatibility intent.
What can go wrong: Do not localize machine field names in a way that breaks parsers. Better wording: “The consumer understands the stated schema versions.”
Verify: Test old and new messages against consumers. Record the configuration and observation time in a multilingual incident log before making the claim public.
52. Monitoring
Publish errors, oldest unacked age, delivery attempts and acknowledgment errors can describe service behavior. None alone proves full end-to-end business success.
What can go wrong: Do not use a green transport dashboard as a payment receipt. Better wording: “The observed service metric is healthy in its defined scope.”
Verify: Correlate subscription and downstream logs. Record the configuration and observation time in a multilingual incident log before making the claim public.
53. Regional boundaries
Service guarantees, resource locations and publisher regional behavior matter to ordering and exactly-once claims. A global audience needs the stated Region.
What can go wrong: Do not call a regional guarantee worldwide and synchronous. Better wording: “The stated property is scoped to this region and setup.”
Verify: Read configured location and client endpoints. Record the configuration and observation time in a multilingual incident log before making the claim public.
54. Customer-facing wording
A support response should distinguish accepted publication, delivery attempt, successful acknowledgment, downstream completion and message expiry.
What can go wrong: Do not reassure users using an unverified final state. Better wording: “The event was accepted; downstream completion remains under investigation.”
Verify: Cite the observed stage and next check. Record the configuration and observation time in a multilingual incident log before making the claim public.
The difference between a message ID and an acknowledgment ID
A message ID identifies a Pub/Sub accepted publication. An acknowledgment ID is associated with a particular delivery and may become invalid after another valid delivery under the exactly-once feature. If documentation treats these as interchangeable, retry instructions may use stale acknowledgment IDs or confuse duplicate publications with legitimate redelivery. Keep the identifiers in separate glossary entries and display each in the appropriate API example.
What exactly-once does and does not promise
On supported pull subscriptions, exactly-once delivery lets clients verify successful acknowledgments and prevents delivery of the same Pub/Sub message after successful acknowledgment within the defined regional scope. It does not make an external database transaction atomic with the Pub/Sub ack. A worker can commit a payment and crash before acknowledging; the application must still reconcile the payment if another valid delivery occurs. Nor does this feature undo duplicate publishes that created separate message IDs.
Why acknowledgment timeouts matter
A subscriber with a short acknowledgment deadline may be processing a legitimate task when the deadline expires. Another delivery can then occur even though no error was present in the business logic. Extending deadlines can help but requires correct configuration and monitoring. A translated phrase such as ‘message failed after 30 seconds’ may be incorrect: the server knows only that no successful acknowledgment arrived by the deadline. Keep processing state and acknowledgement state distinct.
A worked replay decision
An operator discovers that yesterday’s reporting consumer wrote incorrect aggregates and wants to replay events. Before seeking to an earlier time or snapshot, check whether the topic or subscription retains the necessary messages and whether acknowledged messages are available for replay. A snapshot is not an eternal full-data backup and its expiration depends on backlog age. The downstream system also needs a reconciliation plan to prevent duplicate aggregate rows. The action changes what a subscription receives; it does not roll the entire company back in time.
Dead-lettering is a diagnosis, not a cure
A subscription can send repeatedly unprocessable messages to a dead-letter topic. That provides a location for inspection and repair, subject to policy, permissions and best-effort forwarding behavior. It does not automatically fix the invalid message or prove that all attempts stopped at an exact count. A useful translated alert says that the event entered a separate failure-handling workflow and identifies who must review it. Do not use ‘resolved’ merely because the normal queue is quiet.
The per-key ordering tradeoff
Ordering keys help preserve related message order, but they create throughput and retry interactions for the same key. If every event uses one key, the system can become a bottleneck despite high overall topic capacity. A reader-friendly example uses customer IDs or course IDs and explains why unrelated keys remain independent. The word ordered must be followed by ‘within the relevant key’ where that is the actual guarantee.
A practical localization test
Create a harmless test topic, two subscriptions and synthetic numbered messages. Verify that each subscription acknowledges independently. Induce a processing delay, watch acknowledgment-deadline behavior and compare ordinary redelivery with exactly-once settings where supported. Then enable ordering for a controlled key and examine the effect of a redelivered earlier message. Use the observed trace to review every translated claim. A sentence should never promise more than the configured test demonstrates.
Push and pull are different contracts
Pull subscribers can receive acknowledgment result information and are eligible for certain feature guarantees; push subscribers rely on the response from an HTTP endpoint under the push delivery contract. A push response cannot prove that an external service such as a payment provider has committed its work. Export subscriptions similarly own destination-specific semantics. Translate each subscriber type by its actual workflow rather than borrowing the word ‘success’ from a different API.
Retention is not an erasure certificate
A topic may retain messages and a subscription may retain acknowledged messages for replay. Conversely, ordinary retention can expire accessible data. Neither observation establishes what remains in separate logs, object exports or downstream analytics stores. A privacy notice should distinguish availability through the operational subscription from deletion across all copies. When records must be removed under a formal policy, inspect the full data lifecycle and applicable retention obligations rather than assuming an ack equals universal erasure.
An evidence-first incident worksheet
Record project and topic, subscription name and type, message ID, application event ID, ordering key, publish location, ack deadline, acknowledgment outcome, delivery attempts and final business result. Add the exact time each observation was made and whether the source is producer logs, subscription metrics or downstream service logs. Mark missing evidence as missing; do not turn it into a claim of failure. Only after that worksheet is complete should the translation present a confident diagnosis.
Translating configuration without breaking it
Keep executable tokens exact: orderingKey, ackId, messageId, subscriptions, schema field names and IAM resource identifiers must not be silently rewritten into another language. Translate human-readable descriptions and provide a nearby definition. Put units beside values, especially seconds for acknowledgment deadlines and days for retention. If a feature is restricted to pull subscriptions or one region, place the restriction alongside the headline rather than in a footnote several screens away.
Why service metrics cannot settle a customer complaint
An acknowledged-delivery metric describes the Pub/Sub service state. It does not prove the user received a confirmation email, the analytics model used the correct schema, or a bank accepted a transfer. For a support report, write the latest verified stage and the next dependency still to be checked. That communicates progress without making an invented promise, and it helps teams in different languages coordinate without arguing over what ‘done’ meant.
A compact teaching path
Begin with topic versus subscription, then explain publication versus delivery, and only afterward introduce ordering, acknowledgments and replay. Readers who can identify those layers will understand why a redelivery may be legitimate and why exactly-once delivery does not mean exactly-once side effects. End with a realistic worked example, a checklist of evidence, and links to current vendor documentation. This order provides useful information quickly without sacrificing the careful distinctions a production system requires.
The lasting principle
In a system with multiple subscribers, the same message can be acknowledged in one workflow and outstanding in another. A service guarantee can be conditional on API type, region and configuration. Strong technical translation does not erase those conditions for elegance. It makes them visible in plain language, so an engineer can act, an educator can teach and a customer can understand what has actually been confirmed.
Frequently asked questions
Is exactly-once delivery available for Pub/Sub push subscriptions?
No. The specialized exactly-once delivery feature applies to supported pull subscriptions, including StreamingPull, within a cloud region. Push and export subscriber contracts differ. Translate the mode restriction explicitly.
Does exactly-once eliminate duplicate business actions?
No. Producer retries can create distinct accepted publications, and external databases or APIs are not automatically transactional with subscriber acknowledgments. Design idempotent work and track a stable application event ID.
Why was an acknowledged ordered message delivered again?
Under documented conditions, a redelivered earlier message can trigger subsequent same-key messages to be redelivered, including ones previously acknowledged. Compare server message IDs and delivery history; do not call the event a new business action without evidence.
What does an expired acknowledgment ID mean?
After a newer valid delivery, an older acknowledgment ID may be invalid under exactly-once semantics. It is a delivery-specific token, not the permanent message identifier. Use the latest valid delivery state.
Can a seek operation restore messages that expired?
No. Seek can change the starting position only within supported replay and retention conditions. If relevant messages are no longer retained, a separate archive or source is required.
Are dead-letter attempt counts exact guarantees?
Not universally. Dead-letter forwarding and delivery attempts can have best-effort behavior. Describe the configured threshold, the observed attempts and whether the message actually reached its dead-letter topic.
Official sources and wider reading
Google Cloud Pub/Sub subscription overview; message ordering keys and redelivery; exactly-once delivery restrictions; seek, snapshots and replay. For the global translation architecture, use the Translate Like a Pro index. Always verify the exact deployed settings and up-to-date Google Cloud documentation.