API Error Handling
This document explains how errors are represented in the Dashboard.PT API, common error codes, and strategies for handling errors in your applications.
Error Response Format
When an error occurs, the API will return an appropriate HTTP status code and a JSON response with details:
Content-Type: application/json
{
"status": "error",
"message": "Invalid input",
"details": "Missing required field: graph_id"
}
All error responses include:
- status - Always "error" for error responses
- message - A human-readable error message
- details - (Optional) More specific information about the error
Common Error Status Codes
| Status Code | Description | Common Causes |
|---|---|---|
| 400 Bad Request | Invalid request parameters or body | Missing fields, invalid format, malformed JSON |
| 401 Unauthorized | Authentication failed | Invalid or missing API key |
| 403 Forbidden | Permission denied | Accessing a resource you don't own, expired subscription |
| 404 Not Found | Resource not found | Invalid ID, deleted resource |
| 429 Too Many Requests | Rate limit exceeded | Too many requests in a given time period |
| 500 Internal Server Error | Server-side error | Unexpected errors on the server |
Validation Errors
When validation fails for input data, the API returns a 400 Bad Request status with details about what failed:
Content-Type: application/json
{
"status": "error",
"message": "Validation failed",
"details": {
"graph_id": "Required field is missing",
"data": "Must be an array with at least one element"
}
}
Update Frequency Errors
When attempting to update a graph more frequently than allowed by its update frequency setting:
Content-Type: application/json
{
"status": "error",
"message": "Update not allowed based on frequency setting (daily)"
}
Note
For more information about update frequencies, see the Graph Update Frequency documentation.
Error Handling Best Practices
When working with the Dashboard.PT API, follow these best practices for error handling:
- Always check HTTP status codes - Don't just rely on the response body. Different status codes indicate different types of errors.
- Implement retry logic - For 429 (rate limit) and 500-level errors, implement exponential backoff and retry logic.
- Log detailed error information - Include the full error response in your logs to help with debugging.
- Present user-friendly messages - Translate API error messages into user-friendly language in your application.
- Check for specific error details - The "details" field often contains specific information about what went wrong.
Error Handling Code Examples
JavaScript Example
try {
const response = await fetch(`https://dashboard.pt/api/${endpoint}`, {
method,
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: data ? JSON.stringify(data) : null
});
const result = await response.json();
if (!response.ok) {
// Handle error response
console.error(`API Error (${response.status}):`, result);
// Handle specific status codes
if (response.status === 401) {
// Authentication error - redirect to login or refresh token
} else if (response.status === 429) {
// Rate limit exceeded - implement retry with backoff
}
throw new Error(result.message || 'API request failed');
}
return result;
} catch (error) {
console.error('Request failed:', error);
throw error;
}
}
Want to try it? The free plan has no time limit.
Create a free account