Postconditions: what we check

• send · aws-sns-service-error

  error
  WhenAny AWS service error or network failure: topic does not exist (NotFound), insufficient permissions (AuthorizationErrorException), request throttling (ThrottlingException), invalid parameter (InvalidParameterException), endpoint disabled (EndpointDisabledException), KMS key errors (KMSDisabledException, KMSNotFoundException), service unavailable, or any network-level failure (DNS, timeout, connection refused)
  ThrowsSNSServiceException subclass with error.name set to the specific error code (e.g., "NotFound", "AuthorizationErrorException", "InvalidParameterException", "ThrottlingException", "EndpointDisabledException"). For network errors, throws a generic Error or SdkClientError with a connection/timeout message.
  Required handlingCaller MUST wrap client.send() in try-catch. All SNS operations can fail due to network issues, permission problems, topic deletion, or AWS service outages. Unhandled rejections cause silent message loss (for PublishCommand) or crash notification pipelines. Minimum handling: try { await snsClient.send(new PublishCommand({ TopicArn, Message })); } catch (error) { if (error instanceof SNSServiceException) { console.error(`SNS error [${error.name}]: ${error.message}`); } else { console.error('Network error:', error); } throw error; } For PublishBatchCommand, also check for partial failures in result.Failed array (HTTP 200 returned even when some messages fail).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2][3][4]
• PublishBatchCommand · sns-publish-batch-failed-not-checked

  error
  WhenPublishBatchCommand returns HTTP 200 but response.Failed is non-empty — some messages were NOT delivered to topic subscribers due to endpoint disabled, KMS errors, authorization errors, or per-message parameter violations. Caller does not check response.Failed after the call.
  Required handlingCaller MUST inspect response.Failed after every PublishBatch call and handle or alert on any failed entries. Retry SenderFault=false entries (infrastructure failures); do not retry SenderFault=true entries (caller-side errors). Pattern: const response = await snsClient.send(new PublishBatchCommand({ TopicArn, PublishBatchRequestEntries })); if (response.Failed && response.Failed.length > 0) { const retryable = response.Failed.filter(f => !f.SenderFault); const permanent = response.Failed.filter(f => f.SenderFault); if (permanent.length > 0) { console.error('Permanent batch publish failures:', permanent.map(f => `${f.Id}: ${f.Code}`)); } if (retryable.length > 0) { // retry with exponential backoff } }
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[5][6]
• PublishBatchCommand · sns-publish-batch-request-level-error

  error
  WhenPublishBatchCommand throws a request-level exception before processing any messages: TooManyEntriesInBatchRequestException (>10 messages), EmptyBatchRequestException, BatchEntryIdsNotDistinctException (duplicate Id fields), InvalidBatchEntryIdException (Id doesn't match [A-Za-z0-9_-]{1,80}), or BatchRequestTooLongException (total payload >256KB).
  Required handlingValidate batch size (max 10 entries), unique Ids, and total payload size before calling PublishBatchCommand. Wrap in try-catch to handle SNSServiceException.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• SubscribeCommand · sns-subscribe-subscription-limit-exceeded

  error
  WhenSubscribeCommand throws SubscriptionLimitExceededException when the AWS account has reached the maximum allowed number of SNS subscriptions. Default limit is account-level and requires AWS Support to increase.
  Required handlingWrap SubscribeCommand in try-catch and handle SubscriptionLimitExceededException separately from other errors. When caught, alert operations team and submit AWS Support limit increase request. Do NOT silently swallow the error. Pattern: try { const result = await snsClient.send(new SubscribeCommand({ TopicArn, Protocol, Endpoint })); } catch (error) { if (error instanceof SNSServiceException) { if (error.name === 'SubscriptionLimitExceeded') { // Alert ops team — needs AWS limit increase throw new CapacityError('SNS subscription limit reached', error); } throw error; } throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• SubscribeCommand · sns-subscribe-filter-policy-limit-exceeded

  warning
  WhenSubscribeCommand throws FilterPolicyLimitExceededException when a subscription filter policy is provided and the AWS account has exceeded the maximum number of filter policies across all subscriptions. Filter policies enable per-subscription message routing but are counted at the account level.
  Required handlingCatch FilterPolicyLimitExceededException and alert the operations team. Consider redesigning to use fewer filter policies (e.g., per-topic message attributes instead of per-subscription filtering).
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][8]
• SubscribeCommand · sns-subscribe-pending-confirmation-not-handled

  warning
  WhenSubscribeCommand succeeds but returns "pending confirmation" instead of a real subscription ARN. Caller treats the subscription as active and proceeds to publish messages assuming delivery, but the endpoint (HTTP/S, email) has not yet confirmed the subscription.
  Required handlingAfter SubscribeCommand, check if result.SubscriptionArn === 'pending confirmation'. If so, inform users to check their email/endpoint for a confirmation request. Design subscription confirmation flows for HTTP/S endpoints. Pattern: const result = await snsClient.send(new SubscribeCommand({ TopicArn, Protocol: 'https', Endpoint: url })); if (result.SubscriptionArn === 'pending confirmation') { // Endpoint must call ConfirmSubscription — subscription not yet active await notifyUser('Please confirm your SNS subscription endpoint'); }
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[7][9]
• CreateTopicCommand · sns-create-topic-limit-exceeded

  error
  WhenCreateTopicCommand throws TopicLimitExceededException when the AWS account has reached the maximum number of SNS topics (100,000 standard topics or 1,000 FIFO topics per account).
  Required handlingCatch TopicLimitExceededException and alert the operations team. Audit topic usage to identify unused topics that can be deleted. Request an AWS Support limit increase if needed. Note: CreateTopicCommand is idempotent — calling it with the same topic name does NOT hit the limit again. Only new unique topic names consume the quota.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10][11]
• CreateTopicCommand · sns-create-topic-concurrent-access-exception

  warning
  WhenCreateTopicCommand throws ConcurrentAccessException when multiple callers attempt to tag the same topic simultaneously during creation. This is a race condition specific to CreateTopic with Tags when concurrent requests arrive.
  Required handlingCatch ConcurrentAccessException and retry with exponential backoff (it is transient). Do not propagate ConcurrentAccessException to end users.
  costlowin proddegraded serviceusers seedegraded performancevisibilityvisible
  Sources[10]
• PublishCommand · sns-publish-endpoint-disabled-not-handled

  error
  WhenPublishCommand throws EndpointDisabledException (HTTP 400) when the mobile push endpoint (APNs / FCM device token) has been disabled by the push notification service — typically because the token was revoked, the app was uninstalled, or the provider (Apple/Google) flagged the endpoint as invalid. The endpoint must be deleted and re-registered with a fresh token, OR re-enabled via SetEndpointAttributes before retry.
  Required handlingCatch EndpointDisabledException specifically and route to the device-deregistration flow. Do NOT propagate to user-facing error UI (the user didn't do anything wrong) and do NOT blindly retry. Pattern: try { await snsClient.send(new PublishCommand({ TargetArn: endpointArn, Message })); } catch (error) { if (error instanceof SNSServiceException) { if (error.name === 'EndpointDisabled') { await markEndpointDisabled(endpointArn); return; } if (error.name === 'PlatformApplicationDisabled') { await alertOps('Platform application disabled — check APNs/FCM credentials'); return; } } throw error; }
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2][12][13]
• PublishCommand · sns-publish-kms-error-not-handled

  error
  WhenPublishCommand throws one of the KMS error family — KMSAccessDeniedException, KMSDisabledException, KMSInvalidStateException, KMSNotFoundException, KMSOptInRequired, or KMSThrottlingException — when the destination topic is encrypted at rest with a KMS customer master key and the key is unavailable to the publishing principal. Distinct from generic AuthorizationError because the failure is on the KMS key, NOT the SNS topic.
  Required handlingCatch KMS* error names separately from AuthorizationErrorException. Surface the KMS error code to operators so they investigate the KMS key, not the SNS topic. For KMSThrottlingException specifically, retry with exponential backoff (it is transient). Pattern: try { await snsClient.send(new PublishCommand({ TopicArn, Message })); } catch (error) { if (error instanceof SNSServiceException) { if (error.name.startsWith('KMS')) { if (error.name === 'KMSThrottling') { return retryWithBackoff(() => snsClient.send(...)); } await alertOps(`SNS topic encrypted with disabled/inaccessible KMS key: ${error.name}`); throw new InfrastructureError('SNS topic KMS key unavailable', error); } } throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][14][15]
• ConfirmSubscriptionCommand · sns-confirm-subscription-replay-limit-exceeded

  error
  WhenConfirmSubscriptionCommand throws ReplayLimitExceededException when the same confirmation token has been replayed more times than the AWS-imposed limit allows. Indicates either a misbehaving client retry loop or an attempted token-replay attack. The token becomes permanently unusable; a fresh SubscribeCommand call is required to issue a new one.
  Required handlingCatch ReplayLimitExceededException specifically and trigger a re-subscription flow rather than retrying ConfirmSubscription. Log the event for security review (may indicate token-replay probing) and notify the endpoint owner that re-subscription is required. Pattern: try { await snsClient.send(new ConfirmSubscriptionCommand({ TopicArn, Token })); } catch (error) { if (error instanceof SNSServiceException) { if (error.name === 'ReplayLimitExceeded') { await logSecurityEvent('SNS confirmation token replay limit hit', { TopicArn }); await triggerResubscriptionFlow(TopicArn); return; } if (error.name === 'InvalidParameter') { await notifyUser('Confirmation token expired or invalid — please re-subscribe'); return; } } throw error; }
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[16]
• ConfirmSubscriptionCommand · sns-confirm-subscription-token-invalid-not-handled

  warning
  WhenConfirmSubscriptionCommand throws InvalidParameterException when the token is malformed, expired (older than 2 days), or does not match the TopicArn. The subscription remains in pending state — no exception during SubscribeCommand flagged the problem because confirmation is async.
  Required handlingWhen InvalidParameterException is thrown by ConfirmSubscriptionCommand specifically, surface a clear "your subscription confirmation expired, please re-subscribe" message to the end user. Do not retry with the same token. Pattern: try { await snsClient.send(new ConfirmSubscriptionCommand({ TopicArn, Token })); } catch (error) { if (error instanceof SNSServiceException && error.name === 'InvalidParameter') { return { ok: false, reason: 'token_expired_or_invalid' }; } throw error; }
  costlowin prodsilent failureusers seelost datavisibilitysilent
  Sources[16][9]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.