Composition Signals Reference

When performing federated data composition, the gateway returns structured signals to indicate the status of remote data fetches.

CompositionFailure

The CompositionFailure signal is returned when a remote macroservice hop fails due to network issues, timeouts, or server-side errors.

Schema

Field	Type	Description
composition_error	bool	Always true. Indicates this is a failure signal, not business data.
doctype	string	The name of the DocType that failed to load.
entity_id	string	The ID of the specific resource that failed to load.
reason	string	A human-readable description of the error (e.g., "Connect Timeout").
remote_url	string	The internal URL of the macroservice that was being called.

Example Response

If an Invoice links to a Customer on a remote service that is currently down, the get_composite call will return:

{
  "doctype": "finance.Invoice",
  "id": "INV-001",
  "amount": 500,
  "customer": {
    "composition_error": true,
    "doctype": "crm.Customer",
    "entity_id": "CUST-123",
    "reason": "Remote service returned 503",
    "remote_url": "http://crm-node:8001/api/resource/crm.Customer/CUST-123"
  }
}

Handling Signals in the UI

The Frontend Metadata-driven UI (Blueprints) automatically detects the composition_error flag and renders a "Link Unavailable" badge with a tooltip showing the reason.

If you are writing a custom UI component, you should check for this flag:

if (data.customer?.composition_error) {
  return <ErrorMessage message={data.customer.reason} />;
}