Error Handling Guide

{
  "errors": [
    {
      "message": "Invalid access token: invalid token",
      "extensions": {
        "category": "AUTHENTICATION",
        "code": "INVALID_TOKEN",
        "details": [
          "reason: invalid token"
        ],
        "http_status": 401,
        "request_id": "3e79b5c7c12964230e21ad6548c1bfe9",
        "timestamp": "2025-07-10T14:26:35.41989024Z"
      }
    }
  ],
  "data": null
}

{
  "errors": [
    {
      "message": "Invalid access token: invalid token",
      "extensions": {
        "category": "AUTHENTICATION",
        "code": "INVALID_TOKEN",
        "details": ["reason: invalid token"],
        "http_status": 401,
        "request_id": "3e79b5c7c12964230e21ad6548c1bfe9",
        "timestamp": "2025-07-10T14:26:35.41989024Z"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Permission denied",
      "extensions": {
        "category": "AUTHORIZATION", 
        "code": "PERMISSION_DENIED",
        "http_status": 403
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "API quota exceeded: monthly limit reached",
      "extensions": {
        "category": "RATE_LIMIT",
        "code": "QUOTA_EXCEEDED",
        "http_status": 429,
        "details": ["monthly limit reached"]
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Invalid argument provided",
      "extensions": {
        "category": "VALIDATION",
        "code": "INVALID_ARGUMENT",
        "http_status": 400
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Query complexity limit exceeded: 1500 > 1000",
      "extensions": {
        "category": "VALIDATION",
        "code": "COMPLEXITY_LIMIT_EXCEEDED",
        "http_status": 400,
        "details": ["limit: 1000", "actual: 1500"]
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Quest not found: invalid_id",
      "extensions": {
        "category": "NOT_FOUND", 
        "code": "NOT_FOUND",
        "http_status": 404
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "Internal server error",
      "extensions": {
        "category": "INTERNAL",
        "code": "INTERNAL_ERROR",
        "http_status": 500
      }
    }
  ]
}

// Basic retry example
async function retryRequest(operation, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      const shouldRetry = ['QUOTA_EXCEEDED', 'INTERNAL_ERROR', 'UNAVAILABLE']
        .includes(error.extensions?.code);
      
      if (shouldRetry && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}