docsgetting-startederror-handling

Error Handling

Every error is { success: false, error: { code, message } }. Status codes: 400 INVALID_REQUEST (unknown station/city, bad date, bad format, missing required param), 401 UNAUTHORIZED (missing, invalid, or revoked key), 402 PAYMENT_REQUIRED (plan past_due or cancelled), 403 FORBIDDEN (a dd_mcp_ key used outside /mcp/v1), 429 RATE_LIMITED (per-plan limit exceeded; Retry-After header set — 60s for the minute window, 86400s for the day window), 500 INTERNAL_ERROR. Responses carry Cache-Control: max-age=30, stale-while-revalidate=90, and the server caches most query results for up to 5 minutes. Collectors poll NWS every 5 minutes; /accuracy/freshness reports the current lag.

← Response Format
Station Metadata →
cURL
# Bad request (HTTP 400)
curl -s -H "Authorization: Bearer $API_KEY" "https://api.deltadaemon.com/api/v1/accuracy/summary?format=xml" | jq


{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "format must be json or csv"
  }
}


# Rate limited (HTTP 429, Retry-After: 60)
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (requests per minute). Slow down or upgrade your plan."
  }
}


# Plan limits (shared by REST + MCP)
#   Free        10/min     100/day
#   Pro         60/min  10,000/day
#   Enterprise 300/min 100,000/day
# /public/* (no key): 60/min per IP


# Caching
# Cache-Control: public, max-age=30, stale-while-revalidate=90
# Server-side cache: up to 5 minutes for most queries
# Collectors poll NWS every 5 minutes