Errors

Every error response from the Shuriken API follows a consistent envelope so you can handle failures predictably across all endpoints.

Error format

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Amount must be a positive integer string",
    "details": null
  },
  "requestId": "req_abc123"
}

Field	Description
`error.code`	Machine-readable error code
`error.message`	Human-readable explanation
`error.details`	Optional additional context (may be `null`)
`requestId`	Unique request identifier for debugging

Always include the requestId when contacting support. It lets us trace exactly what happened.

Common error codes

HTTP Status	Code	Typical cause
400	`INVALID_PARAMS`	Missing or invalid parameters
400	`NO_ROUTE`	No swap route found for the given token pair
401	`UNAUTHORIZED`	Missing, invalid, or expired API key
403	`FORBIDDEN`	Key lacks the required permission scope
404	`NOT_FOUND`	Resource does not exist (token, order, etc.)
429	`RATE_LIMITED`	Too many requests - slow down
500	`INTERNAL_ERROR`	Something went wrong on our end

Rate limiting

When you exceed your rate limit, the API returns a 429 response. Check your current usage and limits at any time:

curl -X GET "https://api.shuriken.trade/api/v2/account/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Handling errors

Build resilient integrations by checking the HTTP status code and error.code field:

Python

response = requests.post(
    "https://api.shuriken.trade/api/v2/swap/execute",
    headers=headers,
    json=payload,
)

if response.status_code != 200:
    error = response.json()
    code = error["error"]["code"]

    if code == "NO_ROUTE":
        # Try a different token pair or adjust amount
        pass
    elif code == "RATE_LIMITED":
        # Back off and retry
        pass
    else:
        print(f"Error {code}: {error['error']['message']}")

CLI WebSocket Overview

⌘I

Getting Started

WebSocket

Account

Wallet Groups

Trade Suggestions

Alpha

Portfolio

Swap

Tasks

Tokens

Trigger Orders

Perpetuals

Error format

Common error codes

Rate limiting

Handling errors

​Error format

​Common error codes

​Rate limiting

​Handling errors

Error format

Common error codes

Rate limiting

Handling errors