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

# Errors

> Common error responses and troubleshooting

# Error Responses

The CoinStats API uses standard HTTP status codes to indicate the success or failure of requests.

## HTTP Status Codes

| Status Code | Description |
| - | - |
| `200` | Success - Request completed successfully |
| `400` | Bad Request - Invalid parameters or request format |
| `401` | Unauthorized - Invalid or missing API key |
| `403` | Forbidden - API key lacks permission for this endpoint or plan |
| `404` | Not Found - Resource not found |
| `409` | Conflict - Resource conflict (e.g., transactions not synced) |
| `429` | Too Many Requests - Rate limit or credit limit exceeded |
| `503` | Service Unavailable - Upstream dependency temporarily unavailable |
| `500` | Internal Server Error - Server error |

All error responses share the following shape:

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid parameter: coinId",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/coins/invalid-coin"
}
```

The `requestId` is a unique identifier for the request — include it when contacting support.

## Common Error Responses

### 400 Bad Request

Invalid parameters:

```json theme={null}
{
  "statusCode": 400,
  "message": "Invalid parameter: coinId",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/coins/invalid-coin"
}
```

### 401 Unauthorized

Invalid or missing API key:

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid API key",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/coins"
}
```

### 403 Forbidden

API key does not have permission for this endpoint (e.g., plan-restricted endpoint):

```json theme={null}
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/wallet/defi/v2"
}
```

### 404 Not Found

Resource not found:

```json theme={null}
{
  "statusCode": 404,
  "message": "Coin with id 'invalid-coin' not found",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/coins/invalid-coin"
}
```

### 409 Conflict

Transactions not synced:

```json theme={null}
{
  "statusCode": 409,
  "message": "Transactions not synced. Please call PATCH /transactions",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/portfolio/transactions"
}
```

### 429 Too Many Requests

Rate limit or credit limit exceeded:

```json theme={null}
{
  "statusCode": 429,
  "message": "Insufficient credits for this request",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/coins"
}
```

### 503 Service Unavailable

Upstream service temporarily unavailable (credits charged for the request are automatically refunded):

```json theme={null}
{
  "statusCode": 503,
  "message": "Service temporarily unavailable",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/wallet/balance"
}
```

## Troubleshooting

### Authentication Issues

1. **Check your API key**: Ensure you're using the correct API key
2. **Verify header format**: Make sure the `X-API-KEY` header is properly set
3. **Check key permissions**: Ensure your API key has the necessary permissions

### Rate Limiting

1. **Monitor credit usage**: Check your credit consumption in the dashboard
2. **Optimize requests**: Use filters and pagination to reduce data transfer
3. **Upgrade plan**: Consider upgrading if you consistently hit limits

### Data Not Found

1. **Verify parameters**: Check that all required parameters are provided
2. **Check data availability**: Some data might not be available for all coins/time periods
3. **Use correct IDs**: Ensure you're using the correct coin IDs from the API

### Wallet/Transaction Issues

1. **Sync transactions**: Call the sync endpoint before requesting transaction data
2. **Check wallet address**: Ensure the wallet address is valid and supported
3. **Verify blockchain**: Make sure the blockchain is supported by CoinStats

## Getting Help

<ul><li>**Documentation**: This site contains comprehensive API documentation</li>
<li>**Telegram Chat**: For quick help and to connect with other developers, join our [API Support Telegram group](https://t.me/+JPUMD1QAMTNmNGQy)</li>
<li>**Email Support**: You can reach us directly at [**api.support@coinstats.app**](mailto:api.support@coinstats.app) for personalized assistance.</li></ul>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.