Notification Service API Limitations
This section outlines the limitations of our Notification Service APIs when used with Azure Service Bus Standard tier. Understanding these limitations and following the recommended best practices will help ensure the reliability and efficiency of your notification system.
Entity Path & Name Length
-
Limitation
-
Maximum messaging entity path (queue or topic): ≤ 260 characters
-
Maximum entity name (namespace, subscription, or subscription-rule): ≤ 50 characters
-
-
Notification Service APIs
-
There is no impact on any Notification Service endpoint. We automatically enforce and normalize topic and subscription names (truncating or hashing long identifiers) to keep them within the 260- and 50-character limits.
-
-
Third-Party Integrations
-
If you create topics or subscriptions outside the Notification Service, for example, directly in your own or a partner namespace, you must ensure those names comply with the Azure Service Bus limits to avoid creation failures.
-
Message & Batch Size
-
Limitation
-
Single-message max size: 256 KB (headers + payload)
-
Batch send max size: 256 KB
-
-
Mitigation
-
We automatically
gzip-compress payloads in transit, often pushing the effective capacity beyond 256 KB.
-
-
Impact on Your APIs
-
Message Sending: Payloads must stay under 256 KB. While
gzipcompression helps, plan for scenarios exceeding this limit.
-
-
Best Practice
-
Payload Checks: Integrate a pre-send size check. Rely on
gzipfor compression, but fall back to the claim-check pattern for extremely large messages.
-
Message Property Limits
-
Limitation
-
Per-property size: ≤ 32 KB
-
Cumulative header size (all user + system properties): ≤ 64 KB
-
-
Impact
-
Exceeding these limits raises a
SerializationException.
-
-
Impact on Your APIs
-
Message Sending: Total header size must be ≤ 64 KB; be mindful of heavy custom metadata.
-
Subscriptions & Filters
-
Limitation
-
Subscriptions per topic: max 2,000
-
SQL filters per topic: max 2,000
-
SQL filter condition string length: ≤ 1,024 characters
-
Rule action string length: ≤ 1,024 characters
-
Max expressions per action: 32
-
-
Mitigation
-
Currently, if a single selector (filter) would exceed 1,024 characters (for example, an
OBJECT_ID IN (…)list), our utility automatically breaks it into multiple filters.
-
-
Future Enhancement
-
A new endpoint will soon allow passing multiple selectors in one call for more flexible filter management.
-
-
Impact on Your APIs:
-
/createSubscriber:Do not exceed 2,000 subscriptions on a single topic, or further calls will be rejected. -
SQL selectors you supply must each be ≤ 1,024 characters; our utility will split longer ones automatically.
-
-
Best Practices
-
Subscription Governance: Reuse subscriptions, group consumers, or plan for a topic-per-function strategy to stay under the 2,000 subscriptions limit.
-
Filter Management: Keep filters concise. Trust our automatic splitting for now and the upcoming multi-selector API in the future.
-
Error Handling
-
Recommendation: Catch
QuotaExceededExceptionandSerializationExceptionin your client and return a clear 4XX error with guidance to the user. -
Best Practice
-
Error Handling: Implement robust error handling to gracefully manage exceptions and provide informative feedback to users.
-
Summary of API Impacts
-
/createChannel:-
Ensure generated channel/topic names respect the 260-character path and 50-character name limits.
-
-
/createSubscriber:-
Stay within the 2,000 subscriptions per topic limit.
-
Ensure SQL selectors are ≤ 1,024 characters (automatic splitting is in place for longer selectors).
-
-
Message Sending:
-
Keep payloads under 256 KB (
gzipcompression helps). -
Ensure total header size is ≤ 64 KB.
-
To ensure reliable performance of the /createChannel, /createSubscriber, /closeSubscriber, and /closeChannel APIs on Azure Service Bus Standard tier, please incorporate these limitations and
our built-in mitigations into your application design.
