Skip to content

Latest commit

 

History

History
190 lines (158 loc) · 5.04 KB

ERRORS.md

File metadata and controls

190 lines (158 loc) · 5.04 KB

Error Handling Documentation

Error Response Format

All errors follow a standardized format:

{
  status: "error",
  error: string,      // Human-readable error message
  resolution: string  // Suggested steps to resolve the error
}

Error Categories

1. Validation Errors

INVALID_SERVICE

  • Description: The requested Google API service is not supported
  • Possible Causes:
    • Service name is misspelled
    • Service is not implemented in the server
  • Resolution: Check supported services in API documentation

INVALID_METHOD

  • Description: The requested API method is not supported
  • Possible Causes:
    • Method name is misspelled
    • Method is not implemented for the service
  • Resolution: Verify method name in API documentation

INVALID_ENDPOINT

  • Description: Malformed API endpoint format
  • Possible Causes:
    • Incorrect endpoint format
    • Missing service or method parts
  • Resolution: Use format "service.method" (e.g., "drive.files.list")

MISSING_REQUIRED_PARAMS

  • Description: Required parameters are missing from the request
  • Possible Causes:
    • Required parameters not provided
    • Parameters misspelled
  • Resolution: Check required parameters in API documentation

INVALID_PARAM_TYPE

  • Description: Parameter value type doesn't match expected type
  • Possible Causes:
    • Wrong data type provided
    • Array provided instead of string or vice versa
  • Resolution: Verify parameter types in API documentation

2. Authentication Errors

TOKEN_EXPIRED

  • Description: OAuth token has expired
  • Possible Causes:
    • Token age exceeds expiration time
    • Token invalidated by user
  • Resolution: Server will automatically refresh token, retry request

TOKEN_INVALID

  • Description: OAuth token is invalid
  • Possible Causes:
    • Token revoked
    • Token malformed
  • Resolution: Please authenticate the account, which will grant all necessary permissions

INSUFFICIENT_SCOPE

  • Description: Account needs authentication
  • Possible Causes:
    • Account not authenticated
    • New permissions needed
  • Resolution: Please authenticate the account, which will grant all necessary permissions

3. API Errors

API_ERROR_400

  • Description: Bad Request
  • Possible Causes:
    • Invalid request parameters
    • Malformed request body
  • Resolution: Check request format and parameters

API_ERROR_401

  • Description: Unauthorized
  • Possible Causes:
    • Invalid credentials
    • Token expired
  • Resolution: Check authentication status

API_ERROR_403

  • Description: Forbidden
  • Possible Causes:
    • Insufficient permissions
    • Account restrictions
  • Resolution: Please authenticate the account, which will grant all necessary permissions

API_ERROR_404

  • Description: Resource Not Found
  • Possible Causes:
    • Invalid resource ID
    • Resource deleted
  • Resolution: Verify resource exists

API_ERROR_429

  • Description: Rate Limit Exceeded
  • Possible Causes:
    • Too many requests
    • Quota exceeded
  • Resolution: Implement exponential backoff

API_ERROR_500

  • Description: Internal Server Error
  • Possible Causes:
    • Google API error
    • Server-side issue
  • Resolution: Retry request later

API_ERROR_503

  • Description: Service Unavailable
  • Possible Causes:
    • Google API maintenance
    • Temporary outage
  • Resolution: Retry request later

4. System Errors

SERVICE_INIT_FAILED

  • Description: Failed to initialize Google service
  • Possible Causes:
    • Configuration issues
    • Network problems
  • Resolution: Check server configuration

NETWORK_ERROR

  • Description: Network communication failed
  • Possible Causes:
    • Connection issues
    • Timeout
  • Resolution: Check network connection and retry

Error Handling Best Practices

  1. Always Check Status

    • Verify response status before processing
    • Handle both success and error cases

  2. Implement Retry Logic

    • Retry on transient errors (429, 500, 503)
    • Use exponential backoff
    • Set maximum retry attempts

  3. Handle Authentication Flows

    • Watch for token expiration
    • Handle refresh token flow
    • Re-authenticate when needed

  4. Log Errors Appropriately

    • Include error codes and messages
    • Log stack traces for debugging
    • Don't log sensitive information

  5. User Communication

    • Provide clear, user-friendly error messages
    • Include simple resolution steps
    • Avoid technical jargon in user-facing messages
    • Offer support contact if needed

Example Error Handling

try {
  const response = await makeRequest();
  if (response.status === "error") {
    // Handle error based on type
    switch (response.error) {
      case "TOKEN_EXPIRED":
        // Handle token refresh
        break;
      case "INVALID_PARAM_TYPE":
        // Fix parameters and retry
        break;
      // ... handle other cases
    }
  }
} catch (error) {
  // Handle unexpected errors
  console.error("Request failed:", error);
}