Handling Exceptions
HyperStream service returns a consistent error shape. Your integration should treat error handling as a first-class part of the UX (especially around quote expiry, unsupported assets, and asynchronous settlement outcomes).
Standard error envelope
On non-2xx responses, the body is JSON:
{
"message": "Quote not found or expired",
"name": "QuoteNotFoundException",
"details": { "quoteId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}message
string
Human-readable error message
name
string
Exception class name (use for programmatic handling)
details
object
Additional error context (optional, varies by error type)
See Data Types for the complete list of exception names.
General handling rules
Always check the HTTP status code.
On non-2xx, parse the JSON body and branch on
namefor programmatic handling.Check if the error is retryable based on the HTTP status code (5xx errors are typically retryable, 4xx are not).
For user-facing integrations, surface actionable guidance:
"Quote expired, refresh price"
"Unsupported token on selected chain"
"Wallet address mismatch"
Streaming mode caveats
If you use POST /v1/quotes?mode=stream:
If the request body fails validation, the API returns a normal JSON error (no stream).
Individual route/filler failures are skipped (you may receive fewer routes than the number of fillers).
The NDJSON stream closes cleanly once all fillers have either produced a result or failed.
Exception matrix
ValidationException
400
No
Invalid input (zod validation)
Fix request. Use details[] to highlight invalid fields.
BadRequestException
400
No
Chain/transaction format mismatch, expired quote during deposit build, or other invalid state
Ensure transaction format matches chain type (hex for EVM, base58/base64 for Solana). For expired quotes, re-quote and retry.
CannotFillException
400
No
Filler cannot quote the pair
Try another route, token, or chain.
UnexpectedFromAddressException
400
No
EVM vs Solana address mismatch
Ensure address format matches chain family.
NotSupportedContractException
400
No
Contract/config rejects input
Choose another route or contact support.
BuildDepositParsingException
400
No
Quote payload cannot be parsed
Re-quote and retry once, then fail over.
NotSupportedTokenException
404
No
Token not supported (from deposit/build; the quotes endpoint returns empty routes[] instead)
Use token search endpoints for valid list.
NotSupportedChainException
404
No
Chain not supported (from deposit/build; the quotes endpoint returns empty routes[] instead)
Use chains endpoint for valid list.
NotSupportedAssetReverseContractException
404
No
Contract not configured for chain
Choose another route or contact support.
IntentNotFoundException
404
No
Intent payload missing
Re-quote and re-initiate flow.
QuoteNotFoundException
404
Yes
Quote expired or consumed
Re-quote and rebuild deposit plan.
BroadcastException
400
No
Transaction broadcast failed (insufficient funds, nonce, expired blockhash). details is not exposed; use message for diagnostics.
Check wallet balance and nonce. For Solana, ensure blockhash is fresh. Re-sign and retry if transient.
NotSupportedDepositMethodException
400
No
Requested deposit method not supported by filler
Use a different depositMethod or omit it to use the route's default. Check routes[].depositMethods in the quote response.
DuplicateRecordException
409
No
Duplicate record
Treat as "already registered"; fetch order state.
InternalErrorException
500
Yes
Unhandled server error
Retry with backoff. Escalate if persistent.
Last updated

