- 5 minutes to read

Troubleshooting Azure API Management

This guide helps you diagnose and resolve common issues when integrating Azure API Management with Nodinite logging.

Understanding APIM Response Headers

Azure API Management adds informational headers to responses. These headers are distinct from the headers in your APIM policies and have different meanings. Understanding the difference between response headers and request headers is the first step in troubleshooting unexpected behavior.

Header Direction Purpose
Ocp-Apim-Subscription-Key Request Authenticates the caller to APIM — filtered out in logging policies
Ocp-Apim-Trace Request Asks APIM to attach trace output to the response
Ocp-Apim-Trace-AuthorizationExpired Response APIM signals that the subscription's tracing authorization has expired
Ocp-Apim-Request-Id Response APIM correlation ID for the request

Important

Receiving an Ocp-Apim-Trace-AuthorizationExpired response header does not indicate a failed API call. It is informational. The actual HTTP status code (e.g., 200 OK) is the authoritative result.

Ocp-Apim-Trace-AuthorizationExpired in Response

Symptoms

Your agent or client receives a response that contains:

"Ocp-Apim-Trace-AuthorizationExpired": "Tracing authorization for this subscription has expired on 2024-09-23T09:14:13.4496378Z"

The API call itself succeeds (e.g., HTTP 200), but this header appears alongside normal response headers.

Root Cause

APIM supports request tracing for debugging policy execution. Tracing requires an authorization token that is time-limited. When that token expires, APIM includes Ocp-Apim-Trace-AuthorizationExpired in every response for that subscription to signal that trace output is unavailable.

This occurs when:

  • The caller sends an Ocp-Apim-Trace: true request header
  • The subscription used by the caller had tracing enabled but the authorization token has expired

Resolution

If your Nodinite Azure Agent or integration client does not need APIM trace output in production, ensure the Ocp-Apim-Trace header is not being sent with requests. Tracing is a diagnostic tool, not required for normal operation.

Check your agent/client configuration and remove or disable any Ocp-Apim-Trace: true header from outbound requests. Once this header is absent, APIM will no longer evaluate trace authorization and the expired header will not appear.

Option 2: Renew the Trace Authorization

If you actively need APIM tracing (e.g., for debugging policy execution), renew the trace authorization for the affected subscription:

  1. Navigate to your APIM service in the Azure Portal
  2. Go to APIs → select the API → Test tab
  3. Select the operation you want to trace
  4. In the Ocp-Apim-Subscription-Key field, choose your subscription
  5. Enable Tracing — Azure will issue a new time-limited trace authorization token
  6. Alternatively, use the Azure CLI:
# List subscription details to verify trace status
az apim subscription show `
  --resource-group <resource-group> `
  --service-name <apim-service-name> `
  --sid <subscription-id>

Tip

Trace authorization tokens are short-lived (typically 1 hour when issued from the Test tab). For longer-lived agent scenarios, use Option 1 and disable tracing rather than repeatedly renewing.

Event Hub Logger Not Found

Symptoms

APIM policy execution fails with an error referencing a missing or unknown logger, or messages are not appearing in Event Hub.

Root Cause

The logger-id in the <log-to-eventhub> policy element references a logger that does not exist or was deleted. A logger cannot be renamed — it must be deleted and recreated.

Resolution

  1. Verify the logger exists using the Azure Management REST API:
GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.ApiManagement/service/{serviceName}/loggers?api-version=2024-05-01
  1. If the logger is missing, recreate it by following the Event Hub Policy setup guide.
  2. Ensure the logger-id in your policy exactly matches the logger name (case-sensitive).

Important

A logger referenced by any active APIM policy cannot be deleted. Remove all policy references before deleting a logger.

Outdated api-version in Management Calls

Symptoms

Azure Management REST API calls to create or manage APIM loggers return unexpected errors or missing fields, and the URL contains api-version=2019-12-01 or earlier.

Root Cause

The Azure API Management REST API evolves over time. Older api-version values may lack support for newer properties or have deprecated behavior.

Resolution

Update all Azure Management REST API calls to use the current stable version:

Operation Correct URL pattern
Create/update logger ...?api-version=2024-05-01
Delete logger ...?api-version=2024-05-01
List loggers ...?api-version=2024-05-01

Refer to the Event Hub Policy documentation for the correct full URL templates.

Messages Not Arriving in Nodinite

Symptoms

Calls are going through APIM (HTTP 200 responses), but no log events appear in Nodinite.

Diagnostic Steps

Work through each layer in order:

Layer What to Check
APIM Policy Is the <log-to-eventhub> or <send-request> block in the correct inbound/outbound section?
Event Hub Are messages arriving in Event Hub? Check the Incoming Messages metric in the Azure portal.
Pickup Service Is the Nodinite Pickup Log Events Service Logging Agent running and connected to the correct Event Hub?
Network Are there network restrictions blocking the Pickup Service from reaching Event Hub? See Network Restrictions & Alternative Solutions.
Retention Has the Event Hub retention period expired? Messages older than the retention window are gone.

Tip

Use the Azure portal Event Hub → Data Explorer to inspect messages in real time and confirm whether APIM is sending them.

Next Step