Errors

All non-GraphQL /v1 HTTP routes return a consistent JSON error envelope for non-2xx responses.

1
{
2
  "error": "Human-readable error string",
3
  "code": "OPTIONAL_MACHINE_CODE"
4
}

error is the compatibility field and is always present. code is a stable machine-readable classifier when available. New codes may be added during v0, but existing code meanings should not change.

Common Codes

SDK Requirements

SDKs should preserve the raw response body, expose parsed error and code helpers where possible, and include HTTP status, method, and path in exception or error objects. SDKs must not log bearer tokens or idempotency keys at default log levels.

GraphQL Errors

GraphQL routes use a GraphQL data / errors envelope instead of the standard TraceDB JSON error envelope.

1
{
2
  "errors": [
3
    {
4
      "message": "Unsupported root field 'unknown'",
5
      "path": ["unknown"],
6
      "extensions": {
7
        "code": "TRACEDB_GRAPHQL_ERROR"
8
      }
9
    }
10
  ]
11
}

Native GraphQL data and errors may both be present when only part of the operation fails.