Changelog
Introduction

Sections

Changelog

Theme switcher

gRPC Error Handling

This section describes the standard gRPC error codes returned by Match-Trade streaming services (Broker-API, Trading-API). These errors represent both business-level validation issues and infrastructure-level problems. Understanding them helps developers quickly identify the root cause of connection failures and build more resilient integrations.

Common gRPC Stream Errors

Below is a list of the most common errors you may encounter when opening or maintaining a gRPC stream.

RESOURCE_EXHAUSTED

Status: Status.RESOURCE_EXHAUSTED

Example message: Grpc connection limit exceeded

What it means: You have reached the maximum number of allowed parallel streams for a given token + permission (e.g., STREAM_QUOTES).

Typical causes:

  • The connection limit (usually around 200 concurrent streams unless configured otherwise) has been exceeded.
  • The client is opening new streams without closing old ones (missing graceful shutdown).
  • Redis-based connection limiter counted too many active streams associated with the same token.

Example scenario:

  • You run multiple microservices subscribing to quotes using the same API token. They restart but do not close their old connections, eventually hitting the limit.

UNAUTHENTICATED

Status: Status.UNAUTHENTICATED

Example message:

  • Invalid or expired token
  • Authentication failed

What it means: The token in the gRPC metadata is missing, expired, or invalid.

Typical causes:

  • Wrong or expired access token.
  • Metadata header not included.
  • Token revoked on the server side.

Notes:

  • The connection is rejected immediately, and this error does not count toward the connection limit.

PERMISSION_DENIED

Status: Status.PERMISSION_DENIED

Example message:

  • Access forbidden: You don't have the required permissions
  • Access forbidden: You don't have access to the following groups: [GROUP]
  • You don't have access to all provided trading account logins

What it means: The token is valid, but it does not have the required permission or scope.

Typical causes:

  • Missing permission like STREAM_TRADING_EVENTS or STREAM_QUOTES.
  • CRM user trying to read data for groups or trading accounts they are not allowed to access.

Example scenario:

  • A CRM user tries to subscribe to events from trading accounts outside of their assigned group.

INVALID_ARGUMENT

Status: Status.INVALID_ARGUMENT

Example message:

  • Invalid argument: Client ID [id] is unknown
  • Unknown group: [group]

What it means: The request contains invalid or unknown parameters.

Typical causes:

  • Subscribing to a client ID or group that does not exist.
  • Passing incorrect instrument symbols (e.g., typo in a symbol name).
  • Invalid filter values in stream subscriptions.

Example scenario:

  • Subscribing to EUR-USD instead of EURUSD causes the server to close the stream with this error.

UNKNOWN

Status: Status.UNKNOWN

Example message:

  • Unsupported stub type
  • Internal server error

What it means: The server hit an unexpected internal error.

Typical causes:

  • Runtime exceptions like NullPointerException.
  • Incompatibility between gRPC library versions (e.g., Kotlin vs Java stubs).
  • Account status not handled correctly by snapshot logic (e.g., LOCKED_CLOSE_ONLY).

Example scenario:

  • The stream is opened for a trading account with a rare status that the server-side mapper does not support yet.

UNAVAILABLE

Status: Status.UNAVAILABLE

Example message:

  • Service unavailable
  • Redis unavailable

What it means: The service or one of its infrastructure dependencies is temporarily down.

Typical causes:

  • Redis outage (used for connection limiting).
  • API service restart or failover.
  • Network or load-balancer issues.

Recommendation:

  • Clients should treat this as a transient failure and retry with exponential backoff.

Stream Behavior and Operational Details

Heartbeat Messages

To avoid silent disconnects caused by proxies (e.g., Cloudflare, Nginx) that close idle connections, all Match-Trade streams send a heartbeat every 60 seconds. This may be an empty message or a message with heartbeat=true.

Server-Side Disconnects on Critical Errors

If the server detects a critical inconsistency (e.g., incorrect evaluation status in Prop Trading), it may intentionally close the stream to prevent sending corrupted or partial data.

Was this section helpful?

What made this section unhelpful for you?

On this page
  • gRPC Error Handling