504 Gateway Timeout: Backend Did Not Respond in Time

Membrane API Gateway returns 504 Gateway Timeout with this page when the HTTP client that forwards to the target sent the request, but the backend did not answer within the read timeout. A slow backend or a read timeout that is too short is to blame.

The Error Response

The response contains the status 504 Gateway Timeout, the title Gateway Timeout, the problem type https://membrane-api.io/problems/internal and a link to this page. The type internal means that the gateway could not complete the processing of the request. In production mode, the title is replaced by Internal Server Error and the details are left out.

If no connection could be set up at all, see connect timeout instead.

When the Read Timeout Applies

The read timeout is set with soTimeout in httpClientConfig. Its default is 0, which means no read timeout: Membrane then waits for the backend indefinitely, and this error cannot occur. You only see it when soTimeout is set in your configuration.

Common Causes

The Backend Is Slow

The backend accepted the request but sent no data for longer than soTimeout, for example because of high load, a long-running operation or locks in a database.

The Read Timeout Is Too Short

The value of soTimeout is below the normal response time of the backend for some requests.

The Retries Are Used Up

Read timeouts are retried only for idempotent requests to a target with several nodes. In all other cases, the first read timeout leads to this response.

How to Fix It

1. Operator: find out why the backend is slow, e.g. load, long-running operations or locks.
2. Operator: set soTimeout to a value above the backend's normal response time.
3. Client: retry later, or raise the client's own timeout if it gives up before the gateway does.

configuration:
  httpClientConfig:
    connection:
      soTimeout: 30000

configuration:
  httpClientConfig:
    connection:
      soTimeout: 30000

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---.

Related Documentation

Configuration reference:

• httpClient
• httpClientConfig
• target

Tutorials with runnable examples:

• First API

← All Membrane error messages