Every error response from the Shuriken API follows a consistent envelope so you can handle failures predictably across all endpoints.
{
"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:
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']}")
