micro/go-micro · error

agent card: status %d

Error message

agent card: status %d

What it means

Card fetches the remote agent's A2A agent card (well-known JSON document) over HTTP. The library throws this error when the HTTP response status is anything other than 200 OK, because a non-200 response means no valid agent card body can be decoded. It wraps only the status code, not the body, so the actual server-side reason (404, 401, 502, etc.) must be inferred from the number.

Source

Thrown at gateway/a2a/client.go:52

	if h != nil {
		c.http = h
	}
	return c
}

// Card fetches the remote agent's Agent Card.
func (c *Client) Card(ctx context.Context) (*AgentCard, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.url+"/.well-known/agent.json", nil)
	if err != nil {
		return nil, err
	}
	resp, err := c.http.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("agent card: status %d", resp.StatusCode)
	}
	var card AgentCard
	if err := json.NewDecoder(resp.Body).Decode(&card); err != nil {
		return nil, err
	}
	return &card, nil
}

// Send sends a text message to the remote agent and returns its reply.
// If the agent returns a task that isn't yet terminal, Send polls
// tasks/get until it completes or ctx is done.
func (c *Client) Send(ctx context.Context, text string) (string, error) {
	task, err := c.SendMessage(ctx, Message{
		Role:      "user",
		Kind:      "message",
		MessageID: uuid.New().String(),
		Parts:     []Part{{Kind: "text", Text: text}},
	})

View on GitHub (pinned to 24529f1404)

Solutions

1. Verify the agent card URL is correct and reachable (curl the endpoint and confirm 200 + JSON).
2. Check that the agent service is running and registered behind the gateway/proxy.
3. If the endpoint requires authentication, configure the client's HTTP transport/headers before calling Card().
4. Inspect the status code in the error message to distinguish not-found (404) from auth (401/403) or upstream failure (5xx).

Example fix

// before
resp, err := http.Get("https://agents.internal:9443")
card, err := client.Card(ctx)
// after
// point the client at the full agent base URL whose well-known path serves the card
card, err := client.Card(ctx) // client base: https://agents.internal:9443/a2a/finance

resp, err := http.Get(agentBase + "/.well-known/agent.json")
if err != nil { return err }
if resp.StatusCode != http.StatusOK {
	return fmt.Errorf("agent card endpoint returned %d", resp.StatusCode)
}
resp.Body.Close()

card, err := c.Card(ctx)
if err != nil {
	if strings.Contains(err.Error(), "status ") {
		// inspect/parse status code; retry on 5xx, fail fast on 4xx
	}
	return err
}

When it happens

Trigger: Calling Card() on an agent whose /.well-known/agent.json (or configured card URL) returns 404 Not Found, 401/403 auth failure, 500 server error, or a proxy/gateway 502/503 response instead of the card JSON.

Common situations: Wrong base URL or port for the agent endpoint; agent service not deployed or crashed behind a load balancer; missing auth token for a protected discovery endpoint; reverse proxy routing the well-known path incorrectly.

Related errors

• API error: nil response
• failed request
• stream API request failed: %w
• API request failed: %w
• failed to read response: %w

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/39f8216497f8f971. Report an issue: GitHub.