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
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
UNAUTHENTICATED
Status: Status.UNAUTHENTICATED
Example message:
Invalid or expired tokenAuthentication 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
PERMISSION_DENIED
Status: Status.PERMISSION_DENIED
Example message:
Access forbidden: You don't have the required permissionsAccess 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
INVALID_ARGUMENT
Status: Status.INVALID_ARGUMENT
Example message:
Invalid argument: Client ID [id] is unknownUnknown 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
UNKNOWN
Status: Status.UNKNOWN
Example message:
Unsupported stub typeInternal 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
UNAVAILABLE
Status: Status.UNAVAILABLE
Example message:
Service unavailableRedis 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 few 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.
On this page
- gRPC Error Handling