Skip to main content

​
Overview

The /fail endpoint demonstrates how KrakenD handles partial failures when aggregating data from multiple backends. One backend succeeds while another intentionally fails, showing the gateway’s fault tolerance behavior.

​
Endpoint Details

  • Method: GET
  • Path: /fail
  • Authentication: None required

​
Try It

curl -i http://localhost:8080/fail

​
What It Demonstrates

This endpoint aggregates data from two backends:
  1. A successful backend that returns user data
  2. A deliberately failing backend with an unresolvable hostname
The gateway returns the successful response and includes a special header indicating partial completion.

​
Configuration

From config/krakend/krakend.json: 
{
  "endpoint": "/fail",
  "backend": [
    {
      "url_pattern": "/user/1.json",
      "group": "user"
    },
    {
      "host": ["http://fake_url_that_should_not_resolve.tld"],
      "url_pattern": "/",
      "group": "none"
    }
  ]
}

​
Response Behavior

​
Successful Backend

The first backend returns user data from the fake API: 
{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  }
}

​
Failed Backend

The second backend attempts to connect to http://fake_url_that_should_not_resolve.tld, which does not exist and will timeout or fail to resolve.

​
Response Headers

KrakenD adds a special header to indicate incomplete aggregation: 
X-KrakenD-Completed: false
This header tells clients that not all backends responded successfully.

​
Expected Response

HTTP/1.1 200 OK
X-KrakenD-Completed: false
Content-Type: application/json

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  }
}
Notice:
  • The request still returns 200 OK despite one backend failing
  • The successful backend data (user) is included
  • The failed backend data (none group) is omitted
  • The X-KrakenD-Completed: false header indicates partial failure

​
Key Concepts

​
Partial Failure Handling

KrakenD’s default behavior for aggregated endpoints:
  • Returns HTTP 200 if at least one backend succeeds
  • Includes data from successful backends only
  • Adds X-KrakenD-Completed: false header when any backend fails

​
Backend Groups

Each backend is assigned to a group: 
{
  "url_pattern": "/user/1.json",
  "group": "user"
}
The group name becomes the key in the aggregated response. If a backend fails, its group is absent from the response.

​
Timeout Behavior

The failing backend will wait until timeout before the response is returned. The default timeout is specified in the main configuration: 
{
  "timeout": "3000ms"
}
If the fake URL takes longer than 3 seconds to fail, the request completes with available data.

​
Use Cases

This pattern is useful for:

​
1. Optional Data Sources

When some data is optional and the endpoint should succeed even if that data is unavailable: 
{
  "endpoint": "/user-dashboard",
  "backend": [
    {
      "url_pattern": "/users/{id}",
      "group": "user"
    },
    {
      "url_pattern": "/recommendations/{id}",
      "group": "recommendations"
    }
  ]
}
If recommendations service is down, the dashboard still loads with user data.

​
2. Graceful Degradation

Provide core functionality even when auxiliary services fail: 
{
  "endpoint": "/product/{id}",
  "backend": [
    {
      "url_pattern": "/products/{id}",
      "group": "product"
    },
    {
      "url_pattern": "/reviews/{id}",
      "group": "reviews"
    }
  ]
}
Show product details even if reviews are unavailable.

​
3. Client-Side Error Handling

Clients can check the X-KrakenD-Completed header to detect partial failures: 
fetch('/fail')
  .then(response => {
    const isComplete = response.headers.get('X-KrakenD-Completed') !== 'false';
    
    if (!isComplete) {
      console.warn('Some data may be missing due to backend failure');
      // Show warning to user
    }
    
    return response.json();
  });

​
Comparison with Sequential Calls

FeatureAggregation (/fail)Sequential Calls
Backend callsParallelSequential
Partial failureReturns partial dataStops at first failure
Use caseIndependent data sourcesDependent operations
HeaderX-KrakenD-CompletedNot applicable

​
Alternative Behavior

If you want the endpoint to fail completely when any backend fails, configure backend validation: 
{
  "endpoint": "/strict-aggregation",
  "backend": [
    {
      "url_pattern": "/service1",
      "group": "service1"
    },
    {
      "url_pattern": "/service2",
      "group": "service2"
    }
  ],
  "extra_config": {
    "proxy": {
      "sequential": false
    }
  }
}
However, the default behavior (returning partial data) is more resilient.

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us