AWS rtb-fabric medium security documentation change
Summary
Added documentation for error responses including HTTP status codes, response headers, and JSON error format. Enhanced API operation references and clarified testing instructions.
Security assessment
The change documents critical security-related headers (x-amz-rtb-link-id, x-amz-response-source) for tracing requests and identifying error sources. It provides explicit guidance for handling security-sensitive 4xx/5xx errors and timeouts (408), which helps implement proper error handling and monitoring.
Diff
diff --git a/rtb-fabric/latest/userguide/testing-and-using-links.md b/rtb-fabric/latest/userguide/testing-and-using-links.md index 20f43f95f..8e66a6f57 100644 --- a//rtb-fabric/latest/userguide/testing-and-using-links.md +++ b//rtb-fabric/latest/userguide/testing-and-using-links.md @@ -6,0 +7,2 @@ +Error responses + @@ -15 +17 @@ Link addresses will only be visible and accessible from within your VPC. - 1. The URL components in the example below will come from your API responses. If you don't have them at hand, your Gateway ID and Link ID can be found via the AWS Management Console, or by invoking the ListGateways and ListLinks operations outlined in [RTB Fabric API Reference](https://docs.aws.amazon.com/rtb-fabric/latest/api/welcome.html) + 1. The URL components in the following example come from your API responses. If you don't have them at hand, you can find your gateway ID and link ID in the AWS Management Console, or by calling the [ListRequesterGateways](https://docs.aws.amazon.com/rtb-fabric/latest/api/API_ListRequesterGateways.html), [ListResponderGateways](https://docs.aws.amazon.com/rtb-fabric/latest/api/API_ListResponderGateways.html), or [ListLinks](https://docs.aws.amazon.com/rtb-fabric/latest/api/API_ListLinks.html) operation. @@ -17 +19 @@ Link addresses will only be visible and accessible from within your VPC. - 2. From the command line, use `curl` to send a POST request to the Link. Supply an OpenRTB payload to validate full end-to-end requests to your partner, or an empty body to simply test connectivity. See below for a `curl` example in the us-east-1 region. + 2. From the command line, use `curl` to send a POST request to the link. Supply an OpenRTB payload to validate end-to-end requests to your partner, or an empty body to test connectivity. The following example shows a request in the us-east-1 Region. @@ -22 +24,13 @@ Link addresses will only be visible and accessible from within your VPC. -Any additional URL or path params that your partner expects can be appended to the Link URI. +You can append additional URL or path parameters that your partner expects to the link URI. + + + + +Each response includes the `x-amz-rtb-link-id` and `x-amz-response-source` headers. The `x-amz-response-source` header identifies the component that produced the response (for example, RTB Fabric, a module, or the responder), which is the first signal to check when triaging an unexpected response. For the full header contract, see [Common response headers](./common-response-headers.html). + +## Error responses + +When a request does not succeed, the gateway returns an HTTP error response with a JSON body in the following shape. + + + {"error":"true","reason":"message"} @@ -23,0 +38 @@ Any additional URL or path params that your partner expects can be appended to t +The status code tells you where to look first. A `4xx` status code usually means that the request or its configuration needs to change on your side. A `5xx` status code means that RTB Fabric or the responder is the source. A timeout (`408`) is an exception: it is a `4xx` code, but it indicates that the responder did not respond in time. The `reason` field is a free-form text string. The following table lists two common error responses that you can encounter while testing a link. @@ -24,0 +40,4 @@ Any additional URL or path params that your partner expects can be appended to t +Status code | Reason | Meaning +---|---|--- +`503` | `Service temporarily unavailable` | The gateway could not deliver the request to the responder. +`408` | `Timeout waiting for response from responder.` | The responder did not return a response within the gateway's timeout window. @@ -25,0 +45 @@ Any additional URL or path params that your partner expects can be appended to t +The `x-amz-response-source` header on the error response identifies which component produced it.