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:

HTTP/1.1 400 Bad Request
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:

HTTP/1.1 400 Bad Request
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:

HTTP/1.1 429 Too Many Requests
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:

  1. Always check HTTP status codes - Don't just rely on the response body. Different status codes indicate different types of errors.
  2. Implement retry logic - For 429 (rate limit) and 500-level errors, implement exponential backoff and retry logic.
  3. Log detailed error information - Include the full error response in your logs to help with debugging.
  4. Present user-friendly messages - Translate API error messages into user-friendly language in your application.
  5. Check for specific error details - The "details" field often contains specific information about what went wrong.

Error Handling Code Examples

JavaScript Example

async function makeApiRequest(endpoint, method = 'GET', data = null) {
  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