Postconditions: what we check

• download · success

  info
  Whenblob exists and download succeeds
  ReturnsBlobDownloadResponse with readableStreamBody and blob metadata
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• download · blob-not-found

  error
  Whenblob does not exist
  ThrowsRestError with statusCode 404 and x-ms-error-code: BlobNotFound
  Required handlingCaller MUST catch RestError and check error.statusCode === 404 or error.response.headers.get('x-ms-error-code') === 'BlobNotFound' to handle missing blobs.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• download · blob-archived

  error
  Whenblob is in archived tier
  ThrowsRestError with statusCode 409 and errorCode: BlobArchived
  Required handlingCaller MUST catch RestError and handle archived blobs by either rehydrating the blob first or returning appropriate error to user.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• download · network-error

  error
  Whennetwork failure, connection timeout, or DNS resolution failure
  ThrowsError with code ECONNREFUSED, ETIMEDOUT, or ENOTFOUND
  Required handlingCaller MUST catch errors and implement retry logic with exponential backoff for transient network failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• getProperties · success

  info
  Whenblob exists
  ReturnsBlobGetPropertiesResponse with metadata, contentType, lastModified, etc.
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4]
• getProperties · blob-not-found

  error
  Whenblob does not exist
  ThrowsRestError with statusCode 404 and errorCode: BlobNotFound
  Required handlingCaller MUST catch RestError and check error.statusCode === 404 to handle missing blobs. Common pattern is to check existence before accessing properties.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• getProperties · container-not-found

  error
  Whencontainer does not exist
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST catch RestError and distinguish between BlobNotFound and ContainerNotFound to provide appropriate error messages.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• upload · success

  info
  Whenupload succeeds
  ReturnsBlockBlobUploadResponse with requestId, version, and ETag
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• upload · blob-already-exists

  error
  Whenblob exists and If-None-Match: * is set
  ThrowsRestError with statusCode 409 and errorCode: BlobAlreadyExists
  Required handlingCaller MUST catch RestError and check error.statusCode === 409 to handle conflicts when blob already exists.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• upload · container-not-found

  error
  Whencontainer does not exist
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST catch RestError and either create container first or return appropriate error. Common mistake is not checking container existence.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• upload · invalid-blob-type

  error
  Whenblob exists as different type (e.g., page blob)
  ThrowsRestError with statusCode 409 and errorCode: InvalidBlobType
  Required handlingCaller MUST catch RestError and handle type conflicts appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• upload · network-error

  error
  Whennetwork failure during upload
  ThrowsError with code ECONNREFUSED, ETIMEDOUT, or ENOTFOUND
  Required handlingCaller MUST catch errors and implement retry logic for transient failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• uploadFile · success

  info
  Whenfile upload succeeds
  ReturnsBlobUploadCommonResponse with requestId, version, and ETag
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• uploadFile · container-not-found

  error
  Whencontainer does not exist
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST catch RestError and create container before uploading.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• uploadFile · network-error

  error
  Whennetwork failure during multipart upload
  ThrowsError with network error code
  Required handlingCaller MUST catch errors and retry failed uploads with exponential backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• uploadData · success

  info
  Whendata upload succeeds
  ReturnsBlobUploadCommonResponse with requestId, version, and ETag
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• uploadData · container-not-found

  error
  Whencontainer does not exist
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST catch RestError and handle missing container appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• uploadData · network-error

  error
  Whennetwork failure
  ThrowsError with network error code
  Required handlingCaller MUST catch errors and implement retry logic.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3]
• create · success

  info
  Whencontainer creation succeeds
  ReturnsContainerCreateResponse with requestId and ETag
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• create · container-already-exists

  error
  Whencontainer with same name already exists
  ThrowsRestError with statusCode 409 and errorCode: ContainerAlreadyExists
  Required handlingCaller MUST catch RestError and check error.statusCode === 409 to handle existing containers. Common pattern is to check exists() first or catch and continue.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• create · container-being-deleted

  error
  Whencontainer is currently being deleted
  ThrowsRestError with statusCode 409 and errorCode: ContainerBeingDeleted
  Required handlingCaller MUST catch RestError and wait for deletion to complete before retrying.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• create · auth-error

  error
  Whenauthentication fails or insufficient permissions
  ThrowsRestError with statusCode 403
  Required handlingCaller MUST catch RestError with statusCode 403 and handle authentication/authorization failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• delete · success

  info
  Whencontainer deletion succeeds
  ReturnsContainerDeleteResponse with requestId
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[9]
• delete · container-not-found

  error
  Whencontainer does not exist
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST catch RestError and handle missing containers. Common pattern is to check exists() first or catch 404 and treat as success.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• delete · lease-id-missing

  error
  Whencontainer has active lease but lease ID not provided
  ThrowsRestError with statusCode 412 and errorCode: LeaseIdMissing
  Required handlingCaller MUST catch RestError with statusCode 412 and handle lease conflicts.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• exists · success

  info
  Whencheck completes successfully
  Returnsboolean indicating whether container exists
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[10]
• exists · auth-error

  warning
  Whenauthentication fails
  ThrowsRestError with statusCode 403
  Required handlingCaller SHOULD catch RestError for permission errors even when checking existence.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• listContainers · success

  info
  Whenlisting succeeds
  ReturnsAsyncIterableIterator of ContainerItem objects
  Required handlingNo action required — use the returned value as needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[11]
• listContainers · auth-error

  error
  Whenauthentication fails
  ThrowsRestError with statusCode 403
  Required handlingCaller MUST catch RestError when iterating containers to handle auth failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• deleteBlob · blob-delete-snapshots-present

  error
  Whenblob has one or more snapshots and deleteSnapshots option was not set — throws RestError with statusCode 409 and errorCode SnapshotsPresent. A very common silent bug: code that successfully deletes blobs in development (no snapshots) fails in production after versioning or backup jobs create snapshots.
  ThrowsRestError with statusCode 409 and errorCode: SnapshotsPresent
  Required handlingCaller MUST either pass { deleteSnapshots: 'include' } to delete blob and all snapshots together, or catch RestError with statusCode 409 and errorCode SnapshotsPresent to handle the conflict.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[2][12]
• deleteBlob · blob-delete-not-found

  error
  Whenblob does not exist — throws RestError with statusCode 404 and errorCode BlobNotFound. Common in cleanup flows where the blob was already deleted by another process.
  ThrowsRestError with statusCode 404 and errorCode: BlobNotFound
  Required handlingCaller MUST catch RestError and check error.statusCode === 404 to handle already-deleted blobs gracefully. Or use deleteIfExists() which returns { succeeded: false } instead of throwing.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][12]
• deleteBlob · blob-delete-lease-conflict

  error
  Whenblob has an active lease but no lease ID was provided — throws RestError with statusCode 412 and errorCode LeaseIdMissing or LeaseIdMismatchWithBlobOperation.
  ThrowsRestError with statusCode 412 and errorCode: LeaseIdMissing or LeaseIdMismatchWithBlobOperation
  Required handlingCaller MUST provide the active lease ID via options.conditions.leaseId when deleting leased blobs. Catch RestError with statusCode 412 to detect lease conflicts.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][12]
• uploadStream · uploadstream-no-try-catch

  error
  Whenany network failure, auth error, or storage service error during block staging or commit — throws RestError. Because uploadStream() makes multiple HTTP requests (one stageBlock per bufferSize chunk), any intermediate failure throws and the partial upload is left uncommitted.
  ThrowsRestError (from @azure/core-rest-pipeline) with statusCode reflecting the HTTP failure
  Required handlingCaller MUST wrap uploadStream in try-catch. On error, the partially staged blocks are automatically cleaned up by Azure after 7 days, but the upload must be retried from the beginning.
  costhighin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[13][2]
• uploadStream · uploadstream-container-not-found

  error
  Whenthe target container does not exist — throws RestError with statusCode 404 and errorCode ContainerNotFound. Common in multi-tenant apps where containers are provisioned lazily and creation fails silently.
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST ensure container exists before calling uploadStream. Catch RestError with statusCode 404 and errorCode ContainerNotFound to detect missing containers and provision them via containerClient.createIfNotExists().
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][13]
• uploadBlockBlob · uploadblockblob-no-try-catch

  error
  Whenany network failure, auth error, or service error — throws RestError. Same error profile as BlockBlobClient.upload() since it delegates to that method. Commonly called in API route handlers without try-catch because callers assume the container already exists.
  ThrowsRestError (from @azure/core-rest-pipeline) on any service or network failure
  Required handlingCaller MUST wrap in try-catch. The returned blockBlobClient can be used to retry the upload after creating the container if needed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[14][2]
• uploadBlockBlob · uploadblockblob-container-not-found

  error
  Whenthe container encoded in the ContainerClient URL does not exist — throws RestError with statusCode 404 and errorCode ContainerNotFound. Every blob upload to the container fails until the container is created.
  ThrowsRestError with statusCode 404 and errorCode: ContainerNotFound
  Required handlingCaller MUST ensure container exists. Use containerClient.createIfNotExists() before the first upload to a new container.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][14]
• deleteBlob · container-deleteblob-snapshots-present

  error
  Whenblob has snapshots and deleteSnapshots option is not set — throws RestError with statusCode 409 and errorCode SnapshotsPresent. Same behavior as BlobClient.delete(). Affects blobs that have been snapshotted by Azure Backup or versioning policies.
  ThrowsRestError with statusCode 409 and errorCode: SnapshotsPresent
  Required handlingCaller MUST pass { deleteSnapshots: 'include' } option or handle the 409 RestError with errorCode SnapshotsPresent to detect snapshot conflicts.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[2][15]
• deleteBlob · container-deleteblob-not-found

  warning
  Whenthe named blob does not exist — throws RestError with statusCode 404 and errorCode BlobNotFound. Common in eventual-consistency scenarios where the blob was deleted between a list operation and the delete call.
  ThrowsRestError with statusCode 404 and errorCode: BlobNotFound
  Required handlingCaller MUST catch RestError with statusCode 404 to handle already-deleted blobs, or create a BlobClient and use deleteIfExists() instead for idempotent deletion.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][15]
• beginCopyFromURL · begincopy-poll-not-awaited

  error
  Whencaller does not await poller.pollUntilDone() after beginCopyFromURL() — the destination blob remains in 'pending' state while code proceeds as if the copy completed. No exception is thrown; the result is a silently incomplete blob.
  ThrowsDoes NOT throw at copy initiation. The copy runs asynchronously server-side. Only pollUntilDone() throws if the copy fails. Using the destination blob before pollUntilDone() completes results in reading partial or empty content.
  Required handlingCaller MUST await poller.pollUntilDone() after beginCopyFromURL(). Pattern: const poller = await blobClient.beginCopyFromURL(sourceUrl); const result = await poller.pollUntilDone(); Then check result.copyStatus === 'success' before using destination blob.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[16][17]
• beginCopyFromURL · begincopy-source-not-accessible

  error
  Whensource URL is inaccessible to the storage service — throws RestError with statusCode 400 or 403. Causes: source blob requires SAS token not provided, source is in a different account without cross-account SAS, or SAS token expired.
  ThrowsRestError with statusCode 400 or 403 from the storage service
  Required handlingCaller MUST catch RestError on both beginCopyFromURL() and pollUntilDone() calls. For cross-account copies, source URL must include a valid SAS token with read permissions.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[17][16]
• syncCopyFromURL · synccopy-no-try-catch

  error
  Whenany network failure, source access error, or service error — throws RestError. Unlike beginCopyFromURL(), syncCopyFromURL() blocks until the copy completes so the await must be wrapped in try-catch.
  ThrowsRestError (from @azure/core-rest-pipeline) on any service or network failure
  Required handlingCaller MUST wrap syncCopyFromURL in try-catch. For large blobs (>256MB) or when size is unknown, use beginCopyFromURL() instead.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18][19]
• syncCopyFromURL · synccopy-source-inaccessible

  error
  Whensource URL requires authentication the storage service cannot provide — throws RestError with statusCode 403. Also throws for source blob size > 256 MiB limit. Developers testing with public URLs succeed but production with private blobs fails.
  ThrowsRestError with statusCode 403 (auth) or 400 (size limit exceeded)
  Required handlingCaller MUST ensure source URL includes appropriate SAS token for private Azure blobs, and validate source blob size is within 256 MiB limit.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19][18]
• downloadToBuffer · downloadtobuffer-no-try-catch

  error
  Whenany network failure, auth error, or service error during parallel range downloads — throws RestError. If one parallel range request fails mid-download, the entire operation throws and partial data is discarded.
  ThrowsRestError (from @azure/core-rest-pipeline) on any service or network failure
  Required handlingCaller MUST wrap downloadToBuffer in try-catch. For very large blobs, use download() with streaming instead to avoid loading the entire file into memory.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[20][21]
• downloadToBuffer · downloadtobuffer-blob-not-found

  error
  Whenblob does not exist — throws RestError with statusCode 404 and errorCode BlobNotFound. Common in file processing queues where the blob was deleted between enqueue and processing.
  ThrowsRestError with statusCode 404 and errorCode: BlobNotFound
  Required handlingCaller MUST catch RestError with statusCode 404 to distinguish missing blobs from transient network errors. Missing blobs should not be retried.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][20]
• downloadToFile · downloadtofile-no-try-catch

  error
  Whennetwork failure, storage service error, or filesystem error during download — throws RestError (storage errors) or Node.js filesystem Error with code ENOENT, EACCES, or ENOSPC (disk full). The partial file written to disk is NOT automatically cleaned up on failure.
  ThrowsRestError for storage service errors, or Error with code ENOENT/EACCES/ENOSPC for filesystem errors. Partial file remains on disk in both cases.
  Required handlingCaller MUST wrap downloadToFile in try-catch AND clean up the partial file on error: catch (err) { await fs.unlink(filePath).catch(() => {}); throw err; }
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[22][21]
• downloadToFile · downloadtofile-blob-not-found

  error
  Whensource blob does not exist — throws RestError with statusCode 404 and errorCode BlobNotFound. The local file may be created as empty or partially written before the error surfaces from the stream.
  ThrowsRestError with statusCode 404 and errorCode: BlobNotFound
  Required handlingCaller MUST check error.statusCode === 404 to detect missing blobs and delete any partially created local file before re-throwing.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[2][22]
• getUserDelegationKey · getuserdelegationkey-no-try-catch

  error
  Whencredential lacks the Microsoft.Storage generateUserDelegationKey permission — throws RestError with statusCode 403. Also throws RestError on network failures. In production, RBAC permissions are often more restrictive than development environments, causing this to fail at runtime.
  ThrowsRestError with statusCode 403 (permission denied) or 401 (unauthenticated)
  Required handlingCaller MUST wrap getUserDelegationKey in try-catch. The calling identity needs Storage Blob Delegator role (Microsoft.Storage/storageAccounts/blobServices/ generateUserDelegationKey). Cache the returned key until its expiresOn time.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23][24]
• getUserDelegationKey · getuserdelegationkey-expired-window

  warning
  Whenuser delegation key is cached past its expiresOn timestamp — SAS tokens signed with an expired key return 403 AuthorizationPermissionMismatch when clients use them. No error is thrown at key retrieval time.
  ThrowsDoes NOT throw at key retrieval. SAS tokens signed with the expired key return HTTP 403 when used. The error surfaces in downstream client operations, not here.
  Required handlingCaller MUST track key.expiresOn and refresh the key before it expires. Do NOT cache user delegation keys indefinitely. Cache with TTL of expiresOn minus 5 minutes to ensure rotation before expiry.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[24][23]
• generateSasUrl · generatesasurl-not-shared-key

  error
  WhenContainerClient was constructed with TokenCredential (Azure AD) or AnonymousCredential instead of StorageSharedKeyCredential — throws Error locally without making a network call. Teams migrating from account key to managed identity break SAS generation at runtime.
  ThrowsError with message "A shared key credential must be provided to generate a SAS URL". Local error — no network call is made.
  Required handlingCaller MUST use StorageSharedKeyCredential for SAS generation, or use generateUserDelegationSasUrl() with a user delegation key obtained from getUserDelegationKey() when using managed identity / Azure AD credentials.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[25][26]
• generateSasUrl · generatesasurl-expired-sas

  warning
  Whengenerated SAS URL is cached or shared and used after options.expiresOn — clients using the URL receive 403 AuthorizationPermissionMismatch. No error is thrown at generation time; the invalid SAS is silently issued.
  ThrowsDoes NOT throw at SAS generation. Clients using the expired SAS URL receive HTTP 403 AuthorizationPermissionMismatch from the storage service.
  Required handlingCaller MUST set options.expiresOn to an appropriate future time (typically 15 minutes for upload forms, up to 1 hour for download links). Communicate expiry to end users and provide a mechanism to generate fresh URLs.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[26][25]
• exists · blob-exists-no-try-catch

  error
  Whencredential lacks read permission on the blob (statusCode 403), or the storage service throttles the request (statusCode 429), or the account enforces a network ACL the client violates (statusCode 403 AuthorizationFailure) — exists() re-throws RestError. The boolean return contract misleads callers into omitting try-catch.
  ThrowsRestError (from @azure/core-rest-pipeline) — statusCode 403 (auth/ACL), 429 (throttling), or network error code
  Required handlingCaller MUST wrap exists() in try-catch and distinguish (a) the boolean false result (truly missing) from (b) a thrown RestError (auth / throttling / network). Do NOT treat a thrown error as equivalent to "blob does not exist" — that produces silent data loss when permissions regress in production.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[27][2]
• exists · blob-exists-race-condition

  warning
  Whenanother writer creates or deletes the blob between the exists() check and a subsequent operation (download, delete, copy). exists() is a point-in-time read; the result is stale the moment it returns. Time-of-check / time-of-use (TOCTOU) bugs in cleanup jobs and migration scripts.
  ThrowsDoes NOT throw on race. The race manifests in the next operation as a RestError 404 BlobNotFound on download/delete, or 409 BlobAlreadyExists on upload.
  Required handlingCaller SHOULD prefer single-call patterns over check-then-act. For deletes use deleteIfExists(); for conditional uploads use If-None-Match or If-Match conditional headers (options.conditions.ifMatch); for downloads catch the RestError 404 directly. exists() is appropriate ONLY for read-only telemetry / dashboards where staleness is acceptable.
  costmediumin proddelayed failureusers seelost datavisibilitysilent
  Sources[27][28]
• deleteIfExists · blob-deleteifexists-snapshots-present

  error
  Whenblob has one or more snapshots and deleteSnapshots option was NOT set — deleteIfExists throws RestError statusCode 409 errorCode SnapshotsPresent (forwarded from delete()). This is the same critical production bug as BlobClient.delete() — succeeds in development without snapshots, fails in production after Azure Backup or versioning policy creates snapshots.
  ThrowsRestError with statusCode 409 and errorCode: SnapshotsPresent (not swallowed by the "if exists" wrapper)
  Required handlingCaller MUST either pass { deleteSnapshots: 'include' } to delete blob and snapshots together, or wrap deleteIfExists in try-catch and check error.details?.errorCode === 'SnapshotsPresent'. The boolean succeeded flag does NOT cover this case — the call throws before returning.
  costmediumin prodimmediate exceptionusers seelost datavisibilitysilent
  Sources[2][29]
• deleteIfExists · blob-deleteifexists-lease-conflict

  error
  Whenblob has an active lease and no lease ID was provided — deleteIfExists throws RestError statusCode 412 errorCode LeaseIdMissing or LeaseIdMismatchWithBlobOperation. The wrapper does NOT swallow lease errors.
  ThrowsRestError with statusCode 412 and errorCode: LeaseIdMissing or LeaseIdMismatchWithBlobOperation
  Required handlingCaller MUST provide the active lease ID via options.conditions.leaseId for leased blobs. The "if exists" wrapper is NOT a replacement for try-catch around the call.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][29]
• deleteIfExists · blob-deleteifexists-auth-and-throttling

  error
  Whencredential lacks delete permission on the blob (403), or the storage service throttles the request (429 ServerBusy / TimeoutException) — the wrapper re-throws RestError. Cleanup batch jobs that iterate large blob counts commonly trigger throttling; without try-catch the batch halts mid-iteration leaving an inconsistent dataset.
  ThrowsRestError with statusCode 403 (auth) or 429 (throttling — ServerBusy / OperationTimedOut)
  Required handlingCaller MUST wrap deleteIfExists in try-catch even though the name implies safety. For batch cleanup jobs, implement retry-with-backoff on RestError 429 and surface 403 to the operator (RBAC regression, not a transient fault).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][30]
• setTags · settags-precondition-failed

  error
  Whenoptions.conditions.ifTags or .ifMatch is provided and the current blob state does not satisfy the predicate — throws RestError statusCode 412 errorCode ConditionNotMet (ifMatch) or TagConditionNotMet (ifTags). New in 12.30.0; legacy callers pinned to <=12.29.x will not encounter this.
  ThrowsRestError with statusCode 412 and errorCode: ConditionNotMet or TagConditionNotMet
  Required handlingCaller MUST catch RestError with statusCode 412 to detect conditional-write races. Typical pattern is retry with a fresh ETag or back off and re-read tags via getTags() before re-attempting setTags.
  costmediumin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2][31]
• setTags · settags-invalid-tag-value

  error
  Whentag name violates the 1-128 char rule, value violates the 0-256 char rule, tag name contains disallowed characters, or the blob already has 10 tags and a new tag is being added — throws RestError statusCode 400 errorCode InvalidXmlNodeValue / InvalidInput. Often triggered by serializing user-supplied metadata directly into tags without validation.
  ThrowsRestError with statusCode 400 and errorCode: InvalidInput or InvalidXmlNodeValue
  Required handlingCaller MUST validate tag inputs against Azure's rules BEFORE calling setTags, or catch RestError 400 and surface the validation error to the end user. Storing user-supplied data as tags requires explicit allowlist / sanitization.
  costlowin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[32][33]
• setTags · settags-blob-not-found

  error
  Whentarget blob does not exist or is in a deleted state — throws RestError statusCode 404 errorCode BlobNotFound. Often encountered after async deletion in retention workflows.
  ThrowsRestError with statusCode 404 and errorCode: BlobNotFound
  Required handlingCaller MUST catch RestError statusCode 404 to handle the deleted-between-list-and-tag race that retention pipelines hit. Skip and log; do not abort the batch.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][34]

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.

try {
  const containerClient = blobServiceClient.getContainerClient('mycontainer');
  const blockBlobClient = containerClient.getBlockBlobClient('myblob');
  await blockBlobClient.upload(data, data.length);
} catch (error) {
  if (error instanceof RestError && error.statusCode === 404) {
    // Container doesn't exist, create it first
    await containerClient.create();
    await blockBlobClient.upload(data, data.length);
  } else {
    throw error;
  }
}

try {
  const response = await blobClient.download();
  return response;
} catch (error) {
  if (error instanceof RestError && error.statusCode === 404) {
    console.log('Blob not found');
    return null; // Return null for missing blobs
  }
  throw error; // Re-throw other errors
}

try {
  const exists = await containerClient.exists();
  if (\!exists) {
    await containerClient.create();
  }
} catch (error) {
  if (error instanceof RestError && error.statusCode === 409) {
    // Container created by another process, continue
    return;
  }
  throw error;
}