All API errors follow a unified response format:
{ "code" : 40001 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Human readable error message" , "details" : { // Optional additional information } }
HTTP Status Codes Status Description Error Code Range 400 Bad Request 400, 40001-40040 401 Unauthorized 401 403 Forbidden 403, 40301 404 Not Found 404, 40401-40406 429 Too Many Requests 429, 42901-42902 500 Internal Server Error 500, 50001-50036 510 Red Packet Error 51000-51004 520 Webhook Error 52000-52001
Client Errors (400) Parameter Validation Errors Code Name Description Solution 400 BAD_REQUESTBad request Check request format 40001 VALIDATION_ERRORRequest parameters are abnormal or incorrect Check parameter format and values 40002 INVALID_PARAMETERInvalid parameter Check if parameter value meets requirements 40003 INVALID_TOKENInvalid access token Check token format 40004 MISSING_PARAMETERMissing required parameter Add missing required parameters 40005 INVALID_ADDRESSInvalid wallet address format Check address format 40027 INVALID_CURSORInvalid cursor Use valid pagination cursor 40031 INVALID_TIMESTAMPInvalid timestamp format Use ISO 8601 format 40032 INVALID_RESOLUTIONInvalid resolution parameter Use supported K-line periods 40033 INVALID_NUMBER_FORMATInvalid number format Use correct number format
{ "code" : 40002 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Invalid parameter" , "details" : { "parameter" : "resolution" , "value" : "2h" , "allowed_values" : [ "1s" , "1m" , "5m" , "15m" , "1h" , "4h" , "1d" ] } }
Code Name Description Solution 40009 INVALID_TOKEN_ADDRESSInvalid token address Check token contract address 40028 TOKEN_ADDRESSES_LIMIT_EXCEEDEDToken addresses limit exceeded Maximum 100 addresses 40034 TOKEN_ALREADY_CREATEDToken already created Check for duplicate creation
Code Name Description Solution 40029 WALLET_ADDRESSES_LIMIT_EXCEEDEDWallet addresses limit exceeded Maximum 100 addresses
Code Name Description Solution 40010 TRANSACTION_FAILEDTransaction execution failed Check parameters and balance 40011 TRANSACTION_REJECTEDTransaction rejected Check signature and permissions 40012 INVALID_TRANSACTIONInvalid transaction Check transaction structure 40025 TRANSACTION_NOT_SIGNEDTransaction not signed Sign before serialization 40026 TRANSACTION_SIGNATURE_MISSINGTransaction signature missing Add transaction signature 40039 TRANSACTION_SIZE_EXCEEDEDTransaction size exceeded Reduce transaction complexity
DEX Trading Errors Code Name Description Solution 40006 LIQUIDITY_INSUFFICIENTInsufficient liquidity Reduce trade amount 40007 PRICE_IMPACT_TOO_HIGHPrice impact too high Reduce amount or increase slippage 40008 SLIPPAGE_TOO_HIGHSlippage too high Adjust slippage settings 40014 INVALID_AMOUNTInvalid amount Use valid number 40015 AMOUNT_TOO_SMALLAmount too small Increase trade amount 40016 AMOUNT_TOO_LARGEAmount too large Amount exceeds safe range 40017 SAME_TOKEN_SWAPSame token swap Input and output cannot be same 40018 INVALID_SLIPPAGEInvalid slippage value Use valid slippage value 40019 SLIPPAGE_TOO_LOWSlippage too low Slippage must be greater than zero 40020 POOL_NOT_SUPPORTEDPool not supported Use supported pool 40021 UNSUPPORTED_SWAP_MODESwap mode not supported Use supported swap mode 40022 FEE_PARAMETER_ERRORInvalid fee parameter Check fee configuration 40023 ANTI_MEV_REJECTEDAnti-MEV validation failed Check Anti-MEV settings 40030 POOL_INPUT_MISMATCHPool input mismatch Input token doesn’t match pool
{ "code" : 40006 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Insufficient liquidity" , "details" : { "requested_amount" : "1000000000" , "available_liquidity" : "500000000" } }
Code Name Description Solution 40035 INVALID_MARKET_PRICESInvalid market prices Check price parameters 40036 INVALID_ORDER_PARAMETERSInvalid order parameters Check order configuration
Other Client Errors Code Name Description Solution 40013 PARAMETER_ERRORParameter error Must set total or fixed amount 40024 NOT_IMPLEMENTEDMethod not implemented Use implemented methods 40037 UNSUPPORTED_VALUE_TYPEValue type not supported Use supported value types 40038 PARSE_ERRORParse failed Check data format 40040 INVALID_MIGRATE_TYPEInvalid migration type Use valid migration type
Authentication Errors (401) Code Name Description Solution 401 UNAUTHORIZEDUnauthorized. Token is missing or invalid Check Authorization header
{ "code" : 401 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Unauthorized. Token is missing or invalid" }
Handling Example :if ( error . code === 401 ) { // Refresh token const newToken = await getAccessToken (); // Retry request with new token }
Permission Errors (403) Code Name Description Solution 403 FORBIDDENForbidden See details below 40301 INSUFFICIENT_PERMISSIONSInsufficient permissions Obtain required permissions
403 errors can be triggered by:
Quota exhausted : Monthly API call quota depleted, upgrade plan or wait for next month resetBlacklisted : IP or account has been blacklistedNot whitelisted : Request origin not in allowed whitelist
When API quota is exhausted, the gateway returns 403 directly. This differs from 429 (rate limit):
429 : Short-term rate limiting (requests per second/minute exceeded)403 : Account quota limit (monthly usage exhausted) or permission issues { "code" : 403 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Forbidden" }
{ "code" : 40301 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Insufficient permissions" , "details" : { "required_scope" : "kyt.write" , "current_scopes" : [ "kyt.read" ] } }
Resource Not Found Errors (404) Code Name Description Solution 404 NOT_FOUNDResource not found Check if resource exists 40401 POOL_NOT_FOUNDLiquidity pool not found Check pool address and chain 40402 MARKET_INFO_NOT_FOUNDMarket info not found Check if market exists 40403 OPEN_ORDER_NOT_FOUNDOpen order account not found Check order account 40404 ORDER_NOT_FOUNDOrder not found Check order ID 40405 CHAIN_NOT_FOUNDChain not found Use supported chain identifier 40406 DEX_NOT_FOUNDDEX not found Use supported DEX
{ "code" : 40401 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Liquidity pool not found" , "details" : { "chain" : "sol" , "pool_address" : "INVALID_ADDRESS" } }
Rate Limit Errors (429) Code Name Description Solution 429 RATE_LIMITToo many requests. Rate limit reached Wait and retry 42901 API_USAGE_LIMIT_EXCEEDEDAPI usage limit exceeded Upgrade plan or wait for reset 42902 KYT_USAGE_LIMIT_EXCEEDEDKYT API usage limit exceeded Upgrade KYT plan
{ "code" : 429 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Too Many Requests. Rate limit reached" , "details" : { "limit" : 100 , "remaining" : 0 , "reset_at" : 1706745600 } }
Handling Example :if ( response . status === 429 ) { const retryAfter = response . headers . get ( 'Retry-After' ) || 1 ; await sleep ( retryAfter * 1000 ); // Retry request }
Server Errors (500) General Server Errors Code Name Description Solution 500 INTERNAL_SERVER_ERRORInternal server error Retry later 50001 UNKNOWN_ERRORUnknown error Contact support 50005 DATABASE_ERRORData operation failed Retry later 50007 EXTERNAL_SERVICE_ERRORExternal service call failed Retry later 50029 EXTERNAL_API_ERRORExternal API request failed Retry later
Code Name Description Solution 50002 CHAIN_CONNECTION_ERRORBlockchain connection error Check network status 50003 CHAIN_SYNC_ERRORBlockchain synchronization error Wait for sync completion 50004 TRANSACTION_TIMEOUTTransaction timeout Retry or increase timeout 50006 TRANSACTION_ERRORTransaction error Check transaction parameters 50008 CHAIN_NOT_SUPPORTEDChain not supported Use supported chain 50017 INSUFFICIENT_BALANCEInsufficient balance Check account balance 50026 TRANSACTION_SEND_FAILEDTransaction send failed Check network and parameters 50027 TRANSACTION_CONFIRMATION_FAILEDTransaction confirmation failed Check transaction status 50028 TRANSACTION_SIGNATURE_EMPTYTransaction signature is empty Add signature
Code Name Description Solution 50009 DEX_NOT_SUPPORTEDDEX not supported Use supported DEX 50010 DEX_ROUTE_BUILD_FAILEDDEX route build failed Check token pair liquidity 50011 DEX_SWAP_BUILD_FAILEDDEX swap build failed Check trade parameters 50012 DEX_SWAP_SIMULATED_FAILEDDEX swap simulation failed Adjust trade parameters 50019 DEX_AGGREGATOR_NOT_FOUNDDEX aggregator not found Contact support 50020 DEX_BUILDER_NOT_FOUNDDEX builder not found Contact support 50033 CURVE_CALCULATION_ERRORCurve calculation error Check parameters 50034 LOOKUP_TABLE_ERRORAddress lookup table error Retry later 50035 SWAP_ROUTE_ERRORSwap route calculation error Check token pair
Jupiter API Errors Code Name Description Solution 50013 JUPITER_API_UNAUTHORIZEDJupiter API unauthorized Check API key 50014 JUPITER_API_RATE_LIMITJupiter API rate limit Retry later 50015 JUPITER_API_BAD_REQUESTJupiter API bad request Check parameters 50016 JUPITER_API_ERRORJupiter API error Retry later
Configuration and Initialization Errors Code Name Description Solution 50018 PROVIDER_NOT_INITIALIZEDProvider not initialized Configure rpcUrl 50021 ORDER_BUILDER_NOT_FOUNDOrder builder not found Contact support 50022 MARKET_EXPIREDMarket has expired Use valid market 50023 CONFIG_NOT_FOUNDConfig not found Check configuration 50030 FEE_CONFIGURATION_REQUIREDFee configuration required Configure fee 50036 METAFIELD_NOT_FOUNDMetafield not found Check metadata
File Upload Errors Code Name Description Solution 50024 IPFS_UPLOAD_FAILEDIPFS upload failed Retry later 50025 SIGNED_URL_FAILEDSigned URL creation failed Retry later
Bundle Processing Errors Code Name Description Solution 50031 BUNDLE_PROCESSING_FAILEDBundle processing failed Check bundle configuration 50032 TIP_ACCOUNTS_NOT_AVAILABLETip accounts not available Retry later
{ "code" : 50010 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "DEX route build failed" , "details" : { "input_token" : "So11111111111111111111111111111111111111112" , "output_token" : "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" , "reason" : "No valid route found" } }
Red Packet Errors (510) Code Name Description Solution 51000 RED_PACKET_INVALID_PARAMETER_ERRORRed packet parameter error Provide red packet ID or share ID 51001 RED_PACKET_NOT_FOUND_ERRORRed packet not found Check red packet ID 51002 RED_PACKET_WITHDRAWN_ERRORRed packet withdrawn Red packet no longer available 51003 RED_PACKET_ALREADY_CLAIMED_ERRORAlready claimed red packet Each user can claim once 51004 RED_PACKET_TRANSACTION_ERRORRed packet transaction error Retry later
{ "code" : 51003 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "You have already claimed this red packet" }
Webhook Errors (520) Code Name Description Solution 52000 WEBHOOKS_APPLICATION_NOT_FOUNDWebhook application not found Check webhook ID 52001 WEBHOOKS_ENDPOINT_LIMIT_REACHEDWebhook endpoint limit reached Delete unused endpoints
{ "code" : 52001 , "timestamp" : "2026-02-05T10:30:00.000Z" , "message" : "Webhooks endpoint limit reached" , "details" : { "current_count" : 10 , "max_allowed" : 10 } }
Error Handling Best Practices import { ChainStreamClient } from '@chainstream-io/sdk' ; const client = new ChainStreamClient ( process . env . CHAINSTREAM_ACCESS_TOKEN ); async function safeApiCall ( apiFunction ) { try { return await apiFunction (); } catch ( error ) { const { code , message , details } = error ; // Handle errors by category if ( code === 401 ) { // Authentication error: refresh token await refreshToken (); return safeApiCall ( apiFunction ); } if ( code === 429 || code === 42901 || code === 42902 ) { // Rate limit: wait and retry const retryAfter = details ?. reset_at ? ( details . reset_at * 1000 - Date . now ()) : 1000 ; await sleep ( retryAfter ); return safeApiCall ( apiFunction ); } if ( code >= 40000 && code < 41000 ) { // Client parameter error: log and throw console . error ( `Parameter error: ${ message } ` , details ); throw new ValidationError ( message , details ); } if ( code >= 40400 && code < 40500 ) { // Resource not found console . warn ( `Resource not found: ${ message } ` ); return null ; } if ( code >= 50000 ) { // Server error: log and retry console . error ( `Server error: ${ message } ` , details ); await sleep ( 1000 ); return safeApiCall ( apiFunction ); } // Unknown error throw error ; } } // Usage example const tokenInfo = await safeApiCall (() => client . token . getToken ( 'sol' , 'TOKEN_ADDRESS' ) );
Getting Help If you encounter unresolvable errors:
Technical Support Email us with error code and timestamp
Discord Community Join community for help
When reporting issues, please provide the complete error response (including code, timestamp, message, and details) so we can quickly identify the problem.
