HTTP Status Codes

The first step for debugging is to identify if any unexpected HTTP status codes are returned.

Normal operation

Under normal operation, you should observe either:

• 200 OK response, which is the normal response when a request succeeds
• 3xx responses (typically 301, 302 or 303), often with a Location response header, indicating that the client should use a different URL

Other responses (4xx and 5xx) indicate an error condition, and should be investigated:

• HTTP 4xx responses are used to indicate that there was a problem with the HTTP request submitted by the client, such as invalid or missing authentication tokens. In the Tetrate platform, this may also indicate an internal configuration issue such as a misconfiguration of access control.
• HTTP 5xx responses indicate a failure in the server side in any point of the data path. It may indicate an issue with a Gateway configuration, like a missing route, a firewall blocking a network hop, a timeout not being properly configured, or a problem with the application itself.

What generated the unexpected response?

If you see an unexpected HTTP response code, you should verify whether the response code was generated by the Tetrate platform, or directly by your service. The following table considers common error responses generated by the Tetrate platform only.

If you understand the behaviour of your service, you should be be aware of the error response codes it may generate. You can also diagnose where HTTP response codes are generated by looking at Envoy sidecar logs and at Request traces.

Error Responses and their Meanings

HTTP Status Code	Possible Causes
401 (Unauthorized)	This error can be generated by the Tetrate platform when a client is expected to present a valid authentication token, but the token is missing or not valid.
403 RBAC: access denied	This is an internal error message generated by the Tetrate mesh. It indicates that a security policy or network reachability policy has prevented the request from reaching its destination.
403 (Forbidden)	This can indicate that a request contains a valid authentication token, but that the authorizations do not permit the authenticated request to access the desired resource. This response is also used if a request does not match a path rule during validation against an OpenAPI definition
404 (Not Found)	This error can indicate a client error (client submitted a request for resource that did not exist) or a gateway configuration issue. In the gateway situation, a route that matches the request (host header, path and other parameters) is not present.
429 (Too Many Requests)	The Tetrate platform can be configured to perform rate limiting. The 429 response code is used when rejecting a request that exceeds the rate limit.
422 (Unprocessable Entity)	This indicates that the request failed a validation step, for example, when using OpenAPI Spec validation against an OpenAPI definition
503 (Service Unavailable)	This indicates that the request was valid, but the Tetrate platform could not forward it to the intended upstream service. The service may have timed out or failed, or a Gateway in the platform may be misconfigured with an incorrect destination.

Timeouts and Intermittent Errors

Timeouts are not common in the Tetrate platform. Generally, if an internal gateway or the target service times out, a downstream gateway will return a 503 (Service Unavailable) message.

A timeout (no response) suggests either:

• an issue connecting to the very first hop (the edge gateway). Verify that the request is routed to the correct entry point (IP address) and is using the correct port and protocol.
• a slow response, and a mismatch where the edge or downstream gateways are configured with a shorter timeout than the upstream gateway or target service