Establish the shape of database error responses across engines and Neptune versions

Start with connector/utils/isErrorResponse.ts, utils/extractErrorMessage.ts, connector/fetchDatabaseRequest.ts:120, and utils/createDisplayError.ts to trace the current error handling. Use the test-graph-sources skill and AWS Neptune documentation to inspect each listed engine and endpoint, recording observed versus documented shapes. Done means a field inventory by engine and version, a schema recommendation, and a minimal contract covering what GE consumes.

Goal

GE has no single definition of what a database error response looks like, and the two definitions it does have disagree:

• connector/utils/isErrorResponse.ts treats an error as { code, detailedMessage }, both truthy.
• utils/extractErrorMessage.ts probes detailedMessage, message, description, then error, implying at least four shapes reach the display layer. It is called from connector/fetchDatabaseRequest.ts:120 and utils/createDisplayError.ts.

Neither is derived from a documented contract. All 14 call sites of the guard then do throw new Error(data.detailedMessage) and discard code, so today code only acts as a discriminator and detailedMessage is the only field GE consumes.

Before replacing the guard with a schema, establish what the real shapes are, so the schema encodes a contract rather than a fresh guess.

Questions to answer

• What does Neptune actually return for a failed query, per engine: Gremlin over HTTP, openCypher, SPARQL? Field names, types, which are guaranteed present.
• Does that shape differ across Neptune engine versions, and between Neptune Database and Neptune Analytics?
• Are errors delivered as a non-2xx status, a 200 with an error body, or both? The current guard only inspects the parsed body, so a 200-with-error-body is the case it exists for.
• What do the non-Neptune supported endpoints return: Gremlin Server, Blazegraph, and the local Docker containers used for development?
• Which fields does GE genuinely need? detailedMessage is the only one read today. Is code worth keeping for display, logging, or retry decisions, or is it purely a discriminator?
• Does the proxy reshape or wrap any of this on the way through?

Expected Outcome

A field inventory per engine and version, a recommendation on whether one schema or per-engine variants is right, and a proposed minimal schema covering only what GE consumes. Enough for the implementation task to proceed without further discovery.

Use live instances (see the test-graph-sources skill) alongside the AWS Neptune documentation. Record which findings came from observation and which from docs, since the two have diverged before.

Related Issues

• Part of #2171
• Originated from #2162

[!IMPORTANT]
Internal only — this issue is maintained by the core team and is not accepting external contributions.