This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/master by this push:
new 2d7b1ceaea Update Request Retry docs for the 4.x HTTP protocol
2d7b1ceaea is described below
commit 2d7b1ceaea5b12610ffdf489463cdb76a3a5da29
Author: Stephen Mallette <[email protected]>
AuthorDate: Thu Sep 10 20:10:33 2026 +0000
Update Request Retry docs for the 4.x HTTP protocol
The Request Retry section still described the pre-4.x mechanism, telling
readers to detect a transient error via a ResponseStatusCode of
SERVER_ERROR_TEMPORARY (code 596). Those constructs no longer exist after
the move to the HTTP protocol.
Describe how a transient error surfaces under HTTP: an HTTP 500 response
whose body carries an "exception" field set to "ServerEvaluationException",
raised when a server-side provider throws an exception implementing
TemporaryException. Add a Java driver example that inspects
ResponseException.getRemoteException() to branch into retry logic, and note
that raw HTTP clients read the same field from the response body.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/reference/gremlin-applications.asciidoc | 35 ++++++++++++++++++++++--
1 file changed, 32 insertions(+), 3 deletions(-)
diff --git a/docs/src/reference/gremlin-applications.asciidoc
b/docs/src/reference/gremlin-applications.asciidoc
index ed8092c43a..b3d6261b7e 100644
--- a/docs/src/reference/gremlin-applications.asciidoc
+++ b/docs/src/reference/gremlin-applications.asciidoc
@@ -2118,9 +2118,38 @@ transaction remains open until the client explicitly
commits, explicitly rolls b
==== Request Retry
The server has the ability to instruct the client that an error condition is
transient and that the client should
-simply retry the request later. In the event a client detects a
`ResponseStatusCode` of `SERVER_ERROR_TEMPORARY`,
-which is error code `596`, the client may choose to retry that request. Note
that drivers do not have the ability to
-automatically retry and that it is up to the application to provide such logic.
+simply retry the request later. A transient failure arises when a server-side
provider raises an exception that
+implements `TemporaryException`, such as a database locking error that may
resolve on its own for the same request at
+a later time. The server reports this condition as an HTTP `500` response
whose body carries an `exception` field set
+to `ServerEvaluationException`:
+
+[source,json]
+----
+{
+ "message" : "...",
+ "exception" : "ServerEvaluationException"
+}
+----
+
+In the Java driver the failure surfaces as a `ResponseException`, whose
`getRemoteException()` returns the name of
+the server-side exception. Inspecting that value determines whether the
condition is one that may be retried:
+
+[source,java]
+----
+try {
+ client.submit("g.V().count()").all().get();
+} catch (ExecutionException ex) {
+ final Throwable cause = ex.getCause();
+ if (cause instanceof ResponseException &&
+ "ServerEvaluationException".equals(((ResponseException)
cause).getRemoteException())) {
+ // the condition is transient and the request may be retried
+ }
+}
+----
+
+A client that speaks the HTTP protocol directly reads the same `exception`
field from the response body to detect the
+condition. Drivers do not retry automatically, so the retry logic, including
any backoff and limit on the number of
+attempts, is the responsibility of the application.
[[gremlin-server-docker-image]]
=== Docker Image
