What causes "API request to %v failed, code: %v" in hasura/graphql-engine?

Confirm the endpoint URL points at the Hasura server root (e.g. http://localhost:8080), not /v1/graphql

API request to %v failed, code: %v

Error message

API request to %v failed, code: %v

What it means

Returned by the v1version client's GetVersion when the request to the /v1/version endpoint succeeds at the transport level but returns a non-OK HTTP status and the response body is empty (when the body is non-empty, the body itself is used as the error instead). It is tagged KindHasuraAPI, indicating the Hasura server rejected or failed the request.

Source

Thrown at cli/internal/hasura/v1version/version.go:43

func (c *Client) GetVersion() (*hasura.V1VersionResponse, error) {
	var op errors.Op = "v1version.Client.GetVersion"

	b := new(bytes.Buffer)

	resp, err := c.send(nil, b)
	if err != nil {
		return nil, errors.E(op, err)
	}

	if resp.StatusCode != http.StatusOK {
		if b.Len() > 0 {
			return nil, errors.E(op, errors.KindHasuraAPI, b.String())
		} else {
			return nil, errors.E(
				op,
				errors.KindHasuraAPI,
				fmt.Errorf("API request to %v failed, code: %v", c.path, resp.StatusCode),
			)
		}
	}

	o := new(hasura.V1VersionResponse)
	if err := json.NewDecoder(b).Decode(o); err != nil {
		return nil, errors.E(op, fmt.Errorf("decoding API response failed for: %v", c.path))
	}

	return o, nil
}

func (c *Client) send(body any, responseBodyWriter io.Writer) (*httpc.Response, error) {
	var op errors.Op = "v1version.Client.send"

	req, err := c.NewRequest(http.MethodGet, c.path, body)
	if err != nil {
		return nil, errors.E(op, err)

View on GitHub (pinned to 724551b9ae)

Solutions

Confirm the endpoint URL points at the Hasura server root (e.g. http://localhost:8080), not /v1/graphql
Check that any required admin secret/TLS config is passed to the client
Curl the endpoint manually: curl -i <endpoint>/v1/version to see the raw status
If behind a proxy, inspect proxy logs for why the response is empty

Defensive patterns

Strategy: validation

Validate before calling

resp, err := http.Head(endpoint + "/v1/version")
if err != nil || resp.StatusCode != http.StatusOK {
	// fix endpoint/auth before calling GetVersion
}

Type guard

func isHasuraAPIError(err error) bool {
	var e *errors.Error
	return errors.As(err, &e) && e.Kind == errors.KindHasuraAPI
}

Try / catch

v, err := client.GetVersion()
if err != nil {
	if isHasuraAPIError(err) { /* endpoint/auth problem: check URL and admin secret */ }
	return err
}

Prevention

Use the server root URL, not the /v1/graphql path
Probe /v1/version with curl when config changes
Supply admin secret when the endpoint requires it

When it happens

Trigger: Calling GetVersion (e.g. `hasura version` or CLI commands that probe server version) against a URL that returns an empty-body error: 404 from a wrong path or reverse-proxy route, 401/403 from a missing admin secret, 502/503 from a gateway in front of Hasura.

Common situations: Typo in --endpoint, pointing at a GraphQL route instead of the server root, load balancers returning empty 502 responses, or hitting an endpoint that requires auth without supplying the admin secret.

Related errors

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/b8927119f316768d. Report an issue: GitHub.