Error Handling

Ring APIs follow consistent error handling patterns using JSON:API specification for most endpoints. Understanding these patterns is crucial for building robust integrations.

Error Response Format

Most Ring APIs return errors in JSON:API format:

{
  "errors": [{
    "status": "404",
    "title": "Not Found",
    "detail": "The requested resource could not be found"
  }]
}

Common HTTP Status Codes

400 Bad Request

Invalid request parameters or malformed request body.

{
  "errors": [{ "status": "400", "title": "Bad Request", "detail": "Invalid timestamp format" }]
}

Common causes: Invalid parameter values, missing required fields, malformed JSON, invalid date/time formats.

401 Unauthorized

Authentication failure — invalid or expired access token.

{
  "errors": [{ "status": "401", "title": "Invalid Client" }]
}

Common causes: Expired access token, invalid Bearer token format, revoked authentication, missing Authorization header.

403 Forbidden

Valid authentication but insufficient permissions.

{
  "errors": [{ "status": "403", "title": "Out of Scope Access" }]
}

Common causes: Accessing unauthorized device capabilities, insufficient scope, user revoked permissions.

404 Not Found

Requested resource does not exist or is not accessible.

Common causes: Invalid device ID, device removed from account, incorrect API endpoint.

429 Too Many Requests

Rate limit exceeded.

{
  "errors": [{ "status": "429", "title": "Rate Limit Exceeded", "detail": "Too many requests. Please retry after 60 seconds." }]
}

Headers:

Retry-After: Seconds to wait before retrying
X-RateLimit-Limit: Request limit per time window
X-RateLimit-Remaining: Remaining requests in current window

500 Internal Server Error

Server-side error. Retry with exponential backoff.

503 Service Unavailable

Service temporarily unavailable (often device offline).

{
  "errors": [{ "status": "503", "title": "Service Unavailable", "detail": "Device is currently offline" }]
}

Error Handling Implementation

Basic Error Handler

def handle_api_response(response):
    if response.status_code == 200:
        return response.json()
    elif response.status_code == 401:
        refresh_access_token()
        raise AuthenticationError("Access token expired")
    elif response.status_code == 403:
        raise PermissionError("Insufficient permissions")
    elif response.status_code == 404:
        raise ResourceNotFoundError("Resource not found")
    elif response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        raise RateLimitError(f"Rate limited. Retry after {retry_after} seconds")
    elif response.status_code >= 500:
        raise ServerError("Server error occurred")
    else:
        raise APIError(f"Unexpected error: {response.status_code}")

Comprehensive Error Handler with Retries

import time
import requests

def make_api_request(url, headers, max_retries=3, **kwargs):
    base_delay = 1
    
    for attempt in range(max_retries):
        try:
            response = requests.request(url=url, headers=headers, **kwargs)
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 401:
                if attempt == 0:
                    refresh_access_token()
                    headers['Authorization'] = f"Bearer {get_access_token()}"
                    continue
                else:
                    raise Exception("Authentication failed after refresh")
            elif response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue
            elif response.status_code >= 500:
                if attempt < max_retries - 1:
                    time.sleep(base_delay * (2 ** attempt))
                    continue
                else:
                    raise Exception(f"Server error after {max_retries} attempts")
            else:
                raise Exception(f"Client error: {response.status_code}")
                
        except requests.exceptions.RequestException as e:
            if attempt < max_retries - 1:
                time.sleep(base_delay * (2 ** attempt))
                continue
            else:
                raise ConnectionError(f"Failed after {max_retries} attempts: {e}")

Rate Limiter

import time

class RateLimiter:
    def __init__(self):
        self.request_times = []
        self.max_requests = 100  # Don't exceed 100 TPS
        self.time_window = 1
    
    def wait_if_needed(self):
        now = time.time()
        self.request_times = [t for t in self.request_times if now - t < self.time_window]
        
        if len(self.request_times) >= self.max_requests:
            sleep_time = self.time_window - (now - self.request_times[0])
            if sleep_time > 0:
                time.sleep(sleep_time)
        
        self.request_times.append(now)

Error Recovery Strategies

Automatic retry: For transient errors (5xx, network issues)
Token refresh: For authentication errors (401)
Exponential backoff: For rate limiting and server errors
Circuit breaker: For persistent service failures
Graceful degradation: Fallback to cached or limited data
User notification: Inform users of service issues

Next: API Reference →