Monitoring and troubleshooting header policies in ION API Gateway

Monitor header policy execution and diagnose issues such as missing headers, empty context values, and policy conflicts caused by scope and execution order.

Use monitoring tools and controlled tests to verify that header policies execute in the expected flow and scope. Most issues are caused by incorrect policy placement, disabled policies, unavailable context variables, or execution order conflicts.

Monitoring header policy execution

Use ION API Gateway monitoring to confirm that the header policy executes and modifies headers in the intended flow.

What to verify

  • The policy is enabled.
  • The policy is attached to the correct scope (suite or endpoint).
  • The policy is attached to the correct flow (request or response).
  • The policy executes in the expected order relative to other policies.

Verifying effective headers

Verify headers at the point where they matter:

  • Request flow: Confirm the headers that ION API Gateway sends to the backend.
  • Response flow: Confirm the headers that ION API Gateway returns to the client.

Diagnosing missing headers

If a header does not appear in the request or response, verify policy configuration and execution order.

Common causes

  • The policy is attached to the wrong flow.
  • The policy is disabled (enabled="false").
  • The policy is attached to the wrong suite or endpoint.
  • Another policy deletes or overrides the header later in execution.
  • The header references a context variable that is not available at runtime.

Diagnostic approach

  1. Verify policy attachment to the correct flow.
  2. Verify policy attachment to the correct scope.
  3. Review execution order for policies modifying the same header.
  4. Test with a static header value to confirm execution.

Diagnosing empty context variable values

If the header exists but the value is empty, the referenced context variable might not be available for the request.

Common causes

  • The authentication method does not provide the referenced context variable.
  • The variable name is incorrect.
  • The URL structure does not provide expected URL-based values.

Diagnostic approach

  1. Verify the exact variable reference in <headerValue ref="..."/>.
  2. Confirm the authentication method supports the variable.
  3. Test with a static header value to confirm policy execution.
  4. Validate the request URL if using URL-based variables.

Diagnosing policy conflicts and unexpected values

If a header value does not match the expected result, another policy might override it or execution order might change the final value.

Common causes

  • A later policy sets the same header.
  • A policy in another scope overrides the header.
  • The policy references the wrong context variable.
  • A wildcard delete (*) removes headers.

Isolation steps

  1. Identify all policies that modify the same header.
  2. Review policy order within suite and endpoint scope.
  3. Temporarily disable competing policies to isolate behavior.

Diagnosing policy execution failures

If a header policy does not execute or does not apply changes, verify the configuration and request flow conditions.

Common causes

  • The policy XML contains a syntax error.
  • The policy XML does not conform to the supported header policy structure.
  • The policy is not attached to the intended API Suite or endpoint.
  • The policy is attached to a different flow than expected.
  • The policy is disabled (enabled="false").
  • An earlier policy terminates the request flow before the header policy runs.

Diagnostic approach

  1. Validate the policy XML.
    • Check for malformed XML, missing elements, or incorrect nesting.
    • Confirm that required attributes and elements are present.
  2. Verify policy attachment.
    • Confirm that the policy appears in the correct API Suite or endpoint.
    • Confirm that it is attached to the correct flow (request or response).
  3. Verify that the policy is enabled.
  4. Test with a static header value to confirm that the policy executes independently of context variables.
  5. Review earlier request flow policies to determine whether another policy terminates execution.

Log and monitoring checks

  • Review API Gateway monitoring to confirm that the request reaches the expected API Suite and endpoint.
  • Check API Gateway logs for XML parsing or validation errors.
  • Check logs for errors indicating early termination of the request flow.
  • If execution occurs but no header change is visible, verify that later policies do not override or delete the header.

Best practices for troubleshooting

Use controlled testing

Test one change at a time. Begin with a static header value before using context variables.

Manage execution order intentionally

Document which policy owns a header. Order policies to prevent unintended overrides.

Limit header exposure

Remove internal or sensitive headers from responses. Review tenant and identity headers before exposing them to clients.