Reference

Errors and warnings

StockSync separates failures from gaps. A failure is a StockSyncError with a stable code. A gap that does not stop the request, such as a skipped record or an unreadable contract, is a data warning attached to the result.

Error codes

Code	Meaning	Retryable	CLI exit
`INVALID_INPUT`	Malformed symbol, address, query or option	No	2
`UNSUPPORTED_CHAIN`	The chain is neither mainnet (4663) nor testnet (46630)	No	2
`UNSUPPORTED_CONTRACT`	The address has no code, or lacks the required interface	No	2
`NOT_FOUND`	A required record does not exist, such as an unlisted ticker	No	3
`CONFIG_INVALID`	Environment configuration failed validation	No	5
`UPSTREAM_TIMEOUT`	An upstream did not respond in time	Yes	4
`UPSTREAM_UNAVAILABLE`	Network failure or HTTP 5xx	Yes	4
`UPSTREAM_RATE_LIMITED`	HTTP 429	Yes	4
`UPSTREAM_HTTP_ERROR`	Any other unexpected HTTP status	No	4
`UPSTREAM_SCHEMA_MISMATCH`	The upstream responded in a shape StockSync could not validate	No	4
`RPC_ERROR`	A Robinhood Chain RPC read failed	Yes	4

Transient failures are retried inside StockSync before an error is raised: up to three attempts with jittered backoff, honoring Retry-After. retryable: true means trying again later may succeed.

Error messages name the endpoint path, never the full URL, because provider URLs often embed API keys.

How each surface reports errors

SDK: methods throw StockSyncError. error.toJSON() returns code, message, retryable, upstream and issues.
CLI: errors go to stderr with a code: line and a hint, and the process exits with the code above. With --json, stdout receives { "ok": false, "error": { … } } instead.
MCP server: tools return isError: true with { "error": { "code", "message", "retryable" } } as structured content. Invalid arguments return an Input validation error before any upstream is called.

A lookup that finds nothing is not an error: getAsset returns data: null, and the MCP tools return found: false.

Data warnings

Code	Meaning
`UNRECOGNIZED_ENUM_VALUE`	An upstream value StockSync does not know yet; shown as `unrecognized`
`UNDOCUMENTED_RESPONSE_SHAPE`	The upstream used a shape its documentation does not describe
`RECORD_SKIPPED_INVALID`	One record failed validation and was left out
`PARTIAL_RESPONSE`	Only part of the requested data was returned
`SYMBOL_NOT_FOUND`	A requested symbol has no quote
`SERVED_STALE_AFTER_UPSTREAM_ERROR`	An expired response was served because the upstream failed
`QUOTE_UNAVAILABLE`	The quote could not be loaded, so the trading halt is unknown
`ONCHAIN_READ_FAILED`	The contract could not be read; registry values are shown alone
`MULTIPLIER_MISMATCH`	The registry and the contract report different multipliers
`PENDING_MULTIPLIER_PAST_EFFECTIVE_TIME`	A registry pending change has passed its effective time
`ORACLE_PAUSED`	The token reports `oraclePaused()`
`PRICE_FEED_BEYOND_HEARTBEAT`	The Chainlink feed has not updated within its heartbeat
`SECTION_UNAVAILABLE`	One section of an inspection could not be loaded
`WARNINGS_TRUNCATED`	More warnings occurred than a result carries

If every record in a response fails validation, the response is rejected with UPSTREAM_SCHEMA_MISMATCH rather than returned empty.