For the complete documentation index, see llms.txt. This page is also available as Markdown.

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" }
}
Field
Type
Description

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

  1. Always check the HTTP status code.

  2. On non-2xx, parse the JSON body and branch on name for programmatic handling.

  3. Check if the error is retryable based on the HTTP status code (5xx errors are typically retryable, 4xx are not).

  4. 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

Name
HTTP
Retryable
Typical cause
Recommended behavior

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