Configuring HTTP 4xx status codes as errors

You can mark specific or all 4xx HTTP response codes on outgoing requests as errors, enabling accurate error tracking in Instana.

By default, the Instana .NET tracer marks an HTTP span as erroneous only when the HTTP response status code is in the 5xx range (500–599). HTTP 4xx responses on outgoing (client) calls are not treated as errors by default because a 4xx response, such as 404 Not Found, might be an expected outcome in many applications rather than an error condition.

With this feature, you can classify specific or all 4xx status codes from outgoing HTTP calls as errors. Instana then counts them as erroneous operations and includes them in error rate calculations, surfacing them in error dashboards and alerts.

Note:

This configuration applies to only outgoing (client/EXIT) spans, for example, calls made by using HttpClient or HttpWebRequest. Incoming HTTP requests that are handled by your application (ENTRY/server spans) are not affected. A downstream service returning a 4xx response does not indicate that the server handling the incoming request encountered an error.

Span kind behavior

Table 1. Span kind behavior
Span kind	Tracer term	Example	4xx behaviour	5xx behaviour
CLIENT	EXIT span	HttpClient call to external API	Configurable (opt-in)	Always error
SERVER	ENTRY span	Incoming ASP.NET Core request	Never error	Always error

Default behaviour

Without any configuration, the tracer applies the following rules:

HTTP 1xx–4xx status codes: Not marked as errors on any span.
HTTP 5xx status codes: Always marked as errors on both EXIT and ENTRY spans.

This behavior is backward compatible and requires no changes to existing deployments. The configuration options described in this topic add additional error classification on top of the default behavior.

Configuration methods

The following configuration methods are supported, listed in order of precedence:

Environment variables: Set at process startup; highest priority.
YAML configuration file: File path set through INSTANA_CONFIG_PATH.
Agent-based configuration: Delivered by the Instana agent at connection time; lowest priority.

Only one method takes effect per process lifetime. If environment variables are set, YAML and agent configuration are ignored. For more information, see Configuration precedence.

Environment variables

Configure HTTP 4xx error classification by using the following environment variables.

`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS`

Table 2. `INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS` properties
Property	Value
Type	Comma-separated list of integers
Valid range	400–499 only. Values outside this range are ignored.
Default	(not set)
Example	`401,403,429`

Marks the listed HTTP 4xx status codes as errors on EXIT (client) spans. When this variable is set, INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS is ignored.

# Linux / macOS
export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

# Windows (PowerShell)
$env:INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS="401,403,429"

# Docker
ENV INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

# Kubernetes (env section of a container spec)
- name: INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS
  value: "401,403,429"

`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS`

Table 3. `INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS` properties
Property	Value
Type	Boolean string
Accepted values	`true`, `false`
Default	`false`

When set to true, all HTTP 4xx responses (400–499) on EXIT spans are marked as errors. This setting is ignored when INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS is also set.

# Mark all 4xx responses on exit spans as errors
export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true

YAML configuration file

If you already use an Instana configuration file (set through the INSTANA_CONFIG_PATH environment variable), you can add HTTP error classification settings to it alongside other configuration, such as span filtering.

Note:

YAML configuration is ignored if either INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS or INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS environment variables are set.

Mark specific 4xx codes as errors

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403
        - 429

Mark all 4xx codes as errors

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true

Precedence when both configuration keys are defined

When both keys are present, classify-as-errors takes precedence.

com.instana.tracing:
  http:
    exit:
      classify-all-4xx-as-errors: true   # ignored — classify-as-errors is non-empty
      classify-as-errors:
        - 401
        - 403

Supported YAML formats

Table 4. Supported YAML formats
Format	Example
Block list (suggested)	`classify-as-errors:` with the following `- 401` items
Inline array	`classify-as-errors: [401, 403, 429]`
Root key variant	`com.instana.tracing:` or `tracing:`

Agent-based configuration

The Instana agent can deliver HTTP error classification configuration as part of its discovery response. The tracer reads this configuration automatically when it first connects to the agent. No additional setup is required.

Agent-based configuration uses the same key structure as the YAML file. It is the lowest priority source and is silently skipped if environment variables are already set.

Note:

Agent configuration is applied after the application starts and connects to the agent. A short window at startup might occur where agent configuration is not yet active. For time-critical environments, use environment variables instead.

Configuration precedence

When multiple configuration sources are present, the following precedence applies:

Environment Variables  >  YAML file  >  Agent config  >  Default (4xx not error)

After environment variables are detected at startup, they are locked in for the entire process lifetime. YAML and agent configurations are permanently bypassed.

Within-source precedence: regardless of configuration source, when both keys are present, classify-as-errors always takes precedence over classify-all-4xx-as-errors.

Configuration examples

Example 1: Mark only 401 Unauthorized as an error

Use this configuration when your application expects 404 to be normal but 401 always indicates a misconfigured client:

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401

Example 2: Mark authentication and rate-limiting failures as errors

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS=401,403,429

Example 3: Mark all 4xx as errors in a strict environment

export INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true

Example 4: YAML with specific codes

com.instana.tracing:
  http:
    exit:
      classify-as-errors:
        - 401
        - 403

Example 5: Kubernetes deployment

env:
  - name: INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS
    value: "401,403,429"

Best practices

Consider the following best practices when configuring HTTP 4xx status codes as errors.

Use specific codes rather than classifying all 4xx status codes

Setting classify-all-4xx-as-errors: true marks every 4xx response as an error, including codes such as 404 Not Found and 409 Conflict that are often expected and benign. This setting can inflate error counts and trigger false alerts. Prefer listing only the specific codes that genuinely indicate unexpected failures in your application context.

Start narrow, expand as needed

Begin by marking only the codes most clearly associated with errors (typically 401, 403, 429) and observe the effect on your dashboards before adding more codes. Sudden increases in error rate can make it harder to identify real regressions.

Use environment variables in containers and Kubernetes

Environment variables are the most reliable configuration method in containerized environments. They are applied at startup, are visible in pod specs, and cannot be overridden by agent connectivity issues. Use YAML or agent configuration only when centralized management across many services is required.

Do not set both environment variable and YAML for the same setting

When both are present, the environment variable takes precedence and the YAML value is silently ignored. To avoid confusion, use a single configuration method for each deployment and document it.

Avoid classify-all in shared or multi-tenant services

In services consumed by multiple teams or clients, some 4xx codes might be valid for certain callers. Specific code lists give predictable, consistent error reporting without affecting callers for whom those codes are expected.

Troubleshooting

Use the following troubleshooting information to diagnose and resolve common issues with HTTP 4xx error classification.

4xx spans are not marked as errors after configuration

Check that the configuration is loaded once at startup (env vars and YAML) or at first agent connection. Verify environment variables are set before the process starts.
Verify the environment variable is set correctly. Run printenv | grep INSTANA_TRACING (Linux) or Get-ChildItem Env: | Where-Object Name -like "INSTANA_TRACING*" (PowerShell) inside the process environment.
Check the status code range. Only integers in the range 400–499 are accepted. Values such as 500, 200, or non-numeric strings are silently ignored with a warning logged.
Confirm you are looking at an EXIT span, not an ENTRY span.

Error count is unexpectedly high after enabling classify-all

Setting INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS=true marks every 4xx response as an error, including codes such as 404 or 409 that might be expected in your application. Switch to INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS with a specific list of codes to reduce noise.

YAML configuration is not being picked up

Verify that INSTANA_CONFIG_PATH points to a file that exists and is readable by the process user.
Ensure that neither INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS nor INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS environment variables are set. They override YAML silently.
Verify that the YAML key names use hyphens (-), not underscores: classify-as-errors, not classify_as_errors.
Check indentation. YAML is indent-sensitive. http must be a child of com.instana.tracing (or tracing), and exit must be a child of http.

Agent configuration is not being applied

Agent configuration is applied only after the tracer connects to the agent. If the agent is unavailable at startup, the agent configuration might not take effect. Use environment variables for guaranteed startup-time configuration.

Confirm that no environment variables are set that would override the agent configuration:

printenv | grep INSTANA_TRACING

Configuration appears to reset between restarts

Environment variables set in a shell session are not inherited by child processes in some environments. Set them in the system service definition, Docker Compose file, Kubernetes pod spec, or application startup script to ensure they persist across restarts.

Reference

The following reference information summarizes the environment variables, YAML keys, and validation rules.

Environment variables

Table 5. Environment variables
Variable	Type	Default	Description
`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_AS_ERRORS`	Comma-separated integers	(not set)	List of 4xx codes to mark as errors on EXIT spans. Values outside 400–499 are ignored. Takes precedence over `classify-all`.
`INSTANA_TRACING_HTTP_EXIT_CLASSIFY_ALL_4XX_AS_ERRORS`	`true` or `false`	`false`	When `true`, marks all 400–499 responses as errors on EXIT spans. Ignored when `classify-as-errors` is set.
`INSTANA_CONFIG_PATH`	File path	Not set	Absolute path to the YAML configuration file. Shared with span filtering and other tracer features.

YAML keys

Table 6. YAML keys
Key path	Type	Description
`com.instana.tracing.http.exit.classify-as-errors`	List of integers	List of 4xx status codes to mark as errors on EXIT spans.
`com.instana.tracing.http.exit.classify-all-4xx-as-errors`	Boolean	When `true`, all 400–499 responses are marked as errors on EXIT spans.

Validation rules

Values in classify-as-errors must be integers in the range 400–499.
Any value outside this range is ignored and a warning is written to the tracer log.
Non-integer values are ignored and a warning is written to the tracer log.
When both keys are present at the same configuration level, classify-as-errors takes precedence.
5xx status codes (500–599) are always marked as errors and cannot be disabled.
ENTRY (server) spans are never affected regardless of configuration.