Error Handling

Dashtray API error codes and responses

Error Handling

Understand and handle errors from the Dashtray API.

Error Response Format

All errors return a consistent JSON format:

{
  "ok": false,
  "error": "Human-readable description",
  "code": "ERROR_CODE",
  "statusCode": 400
}

HTTP Status Codes

Code	Meaning	Action
200	OK	Request succeeded
400	Bad Request	Check your input
401	Unauthorized	Check your API key
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Wait and retry
500	Server Error	Retry later

Error Codes

VALIDATION_ERROR (400)

Invalid or missing request parameters.

{
  "ok": false,
  "error": "title is required and must be string",
  "code": "VALIDATION_ERROR",
  "statusCode": 400
}

Solutions:

• Check that all required fields are present (title and body)
• Verify field types (string vs number, etc.)
• Ensure the request body is valid JSON

UNAUTHORIZED (401)

Invalid or missing API key.

{
  "ok": false,
  "error": "Invalid API key",
  "code": "UNAUTHORIZED",
  "statusCode": 401
}

Solutions:

• Verify the API key format starts with sk_
• Check the Authorization: Bearer header is set correctly
• Ensure the key hasn’t been revoked
• Generate a new key if uncertain

RATE_LIMIT_EXCEEDED (429)

You’ve exceeded your plan’s per-minute rate limit.

{
  "ok": false,
  "error": "Rate limit exceeded: 100 requests per minute",
  "code": "RATE_LIMIT_EXCEEDED",
  "statusCode": 429
}

Response Headers:

Retry-After: 60

Solutions:

• Wait 60 seconds for the window to reset
• Space out requests to stay under the limit
• Upgrade your plan for higher limits

NOT_FOUND (404)

The requested resource doesn’t exist.

{
  "ok": false,
  "error": "Alert not found",
  "code": "NOT_FOUND",
  "statusCode": 404
}

Solutions:

• Verify the resource ID is correct
• Ensure the resource hasn’t been deleted
• Check that you have access to the resource

INTERNAL_ERROR (500)

Server-side error. Usually temporary.

{
  "ok": false,
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "statusCode": 500
}

Solutions:

• Retry the request after a few seconds
• Use exponential backoff for retries
• Contact support if the error persists

Handling Errors in Code

JavaScript

async function sendNotification(title, body) {
  try {
    const response = await fetch('https://api.dashtray.app/api/v1/notifications/send', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.DASHTRAY_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ title, body })
    });

    const data = await response.json();

    if (!response.ok) {
      throw new Error(`[${data.code}] ${data.error}`);
    }

    return data.notification;
  } catch (error) {
    console.error('Failed to send notification:', error.message);
    // Handle error appropriately
  }
}

Python

import requests

def send_notification(title, body):
    headers = {
        'Authorization': f'Bearer {os.environ.get("DASHTRAY_API_KEY")}',
        'Content-Type': 'application/json'
    }
    
    response = requests.post(
        'https://api.dashtray.app/api/v1/notifications/send',
        headers=headers,
        json={'title': title, 'body': body}
    )
    
    if not response.ok:
        data = response.json()
        raise Exception(f"[{data['code']}] {data['error']}")
    
    return response.json()['notification']

cURL

response=$(curl -X POST https://api.dashtray.app/api/v1/notifications/send \
  -H "Authorization: Bearer $DASHTRAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello", "body": "World"}')

if echo "$response" | grep -q '"ok":false'; then
  echo "Error: $(echo $response | jq .message)"
  exit 1
fi

Retry Strategy

Implement exponential backoff for retries:

async function sendWithRetry(title, description, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await sendNotification(title, description);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Common Mistakes

Don’t hardcode API keys in code. Use environment variables.

// ❌ Bad
const apiKey = "sk_test_...";

// ✅ Good
const apiKey = process.env.DASHTRAY_API_KEY;

Don’t ignore 429 errors. Respect rate limits.

// ❌ Bad
try {
  // send request
} catch (error) {
  // try again immediately
}

// ✅ Good
if (response.status === 429) {
  const resetTime = parseInt(response.headers['x-ratelimit-reset']);
  await delay(resetTime - Date.now());
}

Support

Having issues? Check:

• Quickstart
• Authentication guide
• API Reference
• GitHub Issues