Circuit Breaker

To ensure the stability of the platform by protecting it from excessive load, Custom APIs contain a Circuit Breaker mechanism. This functionality blocks API requests when a specific error threshold is exceeded.

A circuit breaker is configured for every registered endpoint and each incoming request to that endpoint passes through it. How the circuit breaker acts depends on its internal state, which is defined by the recent script execution on the corresponding endpoint. The circuit breaker can be in one of three states: closed, open, or half-open.

The default state of a circuit breaker is closed, which means that the request is allowed to pass through to the implementation script.

If the execution of the implementation script results in an error, this error is tracked. Once the error rate exceeds the threshold of 50%, this process is triggered:

  1. The internal state changes to open. This change is logged.
  2. For 60 seconds, any calls to the failing endpoint return an HTTP status code 503 - Service Unavailable with the error type custom-api-circuit-breaker-error.
  3. After 60 seconds, the internal state changes to half-open. This change is logged.
  4. The circuit breaker tracks the next 10 calls to the failing endpoint. If more than 5 of them fail, return to step 1.
  5. The internal state changes to closed and the endpoint is unblocked. The circuit breaker continues tracking requests to this endpoint. This change is logged.

In the closed state, the circuit breaker will evaluate the previous 100 requests in order to calculate the error rate. This means that at least 50 of them must have failed when the circuit breaker opens.

If Custom API requests return errors of the type custom-api-internal-server-error or custom-api-circuit-breaker-error, use Log Center to investigate the cause.

  1. In Business Manager, navigate to Administration > Site Development > Development Setup.
  2. In the Log Files section, click Log Center.
  3. Select the Day of Year.
  4. In the LCQL field, enter CustomApiCircuitBreaker.
  5. In the query hits, look for a CustomApiInvocationException entry and click its Stack Trace UUID link.
  6. In the stack trace, find the Caused by section. It can contain information about the cause of the failures. Some possible causes include:
  • The script contains a remote call that never returns a response, causing the script execution to time out. In this case, try making an asynchronous call instead.
  • The script contains errors. Fix the code and consider adding error handling measures.