> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shuriken.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Standard error format and common error codes for the Shuriken API.

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

## Error format

```json theme={null}
{
  "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     |

<Tip>
  Always include the `requestId` when contacting support. It lets us trace exactly what happened.
</Tip>

## 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:

```bash theme={null}
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 Python theme={null}
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']}")
```