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 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.
What made this section helpful for you?
What made this section unhelpful for you?
On this page
- gRPC Error Handling