Skip to main content

​
Error Responses

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

​
HTTP Status Codes

Status CodeDescription
200Success - Request completed successfully
400Bad Request - Invalid parameters or request format
401Unauthorized - Invalid or missing API key
403Forbidden - API key lacks permission for this endpoint or plan
404Not Found - Resource not found
409Conflict - Resource conflict (e.g., transactions not synced)
429Too Many Requests - Rate limit or credit limit exceeded
503Service Unavailable - Upstream dependency temporarily unavailable
500Internal Server Error - Server error
All error responses share the following shape: 
{
  "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: 
{
  "statusCode": 400,
  "message": "Invalid parameter: coinId",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/coins/invalid-coin"
}

​
401 Unauthorized

Invalid or missing API key: 
{
  "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): 
{
  "statusCode": 403,
  "message": "Forbidden resource",
  "requestId": "11111111-2222-3333-4444-555555555555",
  "path": "/wallet/defi/v2"
}

​
404 Not Found

Resource not found: 
{
  "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: 
{
  "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: 
{
  "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): 
{
  "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