How to record failed request body correctly in API Management

Hi @jinxjer lee

Thank you for reaching out to Microsoft Q&A.

You’re preserving the request body in inbound and then trying to emit it on error via a <trace> call unfortunately, those <trace> messages don’t end up in the ApiManagementGatewayLogs table by default. Here are a couple of ways to capture only the 400-error payloads:

Enable built-in diagnostics for “Frontend Request” bodies

In your APIM instance, go to “Diagnostic Logs” > “Azure Monitor.”

Enable logging, check Always log errors, and under Additional settings tick Frontend Request (and optionally Backend Request).

Save.

Now every error call (400, 500, etc.) will write the request/response bodies (up to 8 KB each, and a 32 KB total entry limit) into ApiManagementGatewayLogs.

In Log Analytics, you can then run:

ApiManagementGatewayLogs
| where HttpStatusCode == 400
| project TimeGenerated, OperationName, RequestBody, ResponseBody

Use a real logger policy instead of <trace>

Define an Event Hub or Application Insights logger in APIM (under Settings > Loggers).

In your <on-error> block change your <trace> to:

<log-to-eventhub logger-id="your-eventhub-logger">
  {
    "status": @(context.Response.StatusCode),
    "url": "@(context.Request.Url.Path)",
    "body": "@(context.Variables["savedBody"])"
  }
</log-to-eventhub>

Or similarly use <log-to-application-insights> if you prefer App Insights.

This will stream your error payloads off to the configured logger, bypassing the 32 KB diagnostics limit in Azure Monitor.

Adjust your error condition to catch 400s

You currently only log on StatusCode == 500. Change your <when> to:

<when condition="@(context.Response.StatusCode == 400)">
  …your log-to-eventhub or trace…
</when>

Notes:

APIM enforces an 8 KB limit on logged request/response bodies and 32 KB per entry. If your payloads exceed that, they’ll get trimmed.

Traces (<trace>) show up in the Test Console but aren’t pushed into the gateway diagnostic logs table.

ApiManagementGatewayLogs does not store the full request body by default, and traceRecords in this table is not intended to contain arbitrary payloads preserved from policies. To capture failed request bodies selectively (for example, only when a 400 error occurs), use API Management policies and send the body to another sink (such as Application Insights or Event Hubs) from the on-error section.

Key points from the platform behavior:

• Policy execution is split into inbound, backend, outbound, and on-error sections. When an error occurs, remaining steps are skipped and execution jumps to on-error.
• In on-error, only a specific set of policies is allowed, including set-variable, send-request, send-one-way-request, log-to-eventhub, trace, return-response, and others.
• Errors that trigger on-error, or responses with 4xx/5xx status codes, are emitted as Exception telemetry to Application Insights when that integration is enabled.

Given these behaviors, a working pattern to capture failed request bodies while minimizing volume is:

1. In the inbound section, buffer the request body into a variable so it can be reused later.
2. Let the request proceed to the backend as usual.
3. In the on-error section, check context.LastError (or response status) and, only when the backend response is 400, send the buffered body to an external sink using an allowed policy.

Conceptually:

<policies>
  <inbound>
    <!-- Preserve request body in a variable -->
    <!-- Example: use set-variable with a policy expression that reads the body -->
  </inbound>

  <backend>
    <!-- Call backend as usual -->
  </backend>

  <outbound>
    <!-- Normal response handling -->
  </outbound>

  <on-error>
    <!-- Inspect error -->
    <!-- context.LastError provides details such as reason, section, scope -->

    <!-- Conditionally log only failed requests -->
    <!-- For example, use choose + send-request/log-to-eventhub/trace to emit
         the preserved body when the backend returned 400. -->
  </on-error>
</policies>

Because ApiManagementGatewayLogs has fixed columns (such as BackendRequestBody, BackendResponseBody, Errors, LastErrorMessage, LastErrorReason, etc.), it is not possible to push arbitrary trace records with large request bodies into that table via policy. Instead, use:

• Application Insights integration, which records:
  • Request telemetry for frontend calls.
  • Dependency telemetry for backend calls.
  • Exception telemetry for failed requests, including those that triggered on-error or returned 4xx/5xx.
• A trace policy in on-error to emit structured trace messages (including the preserved request body or a truncated version) to Application Insights. Ensure the severity in the trace policy is at least the verbosity configured in Application Insights so traces are ingested.
• Alternatively, log-to-eventhub in on-error to send the failed request body to Event Hubs, where it can be processed or archived.

To keep costs under control for large payloads:

• Only emit logs from on-error when the backend response code is 400.
• Truncate or summarize the body before logging (for example, log only the first N characters or selected fields).
• Use sampling or filters at the sink (Application Insights or Event Hubs consumer) if needed.

ApiManagementGatewayLogs remains useful to identify failures and correlate them (for example, via LastErrorReason, LastErrorMessage, IsRequestSuccess, BackendResponseCode), but the full failed request body should be captured through policies and logged to Application Insights or Event Hubs rather than relying on traceRecords in this table.

References:

• Error handling in API Management policies
• ApiManagementGatewayLogs
• How to integrate Azure API Management with Azure Application Insights
• Policies in Azure API Management
• Queries for the ApiManagementGatewayLogs table
• Tutorial: Debug your APIs using request tracing