Error Handling Documentation 🛠️

All API endpoints handle errors in a consistent and meaningful manner to provide clear feedback to clients. This document outlines the error handling mechanisms for REST (gRPC Gateway) APIs, including the structure of error responses and examples of custom error handling.

Error Structure

REST Error Structure

For REST (gRPC Gateway), errors are returned as JSON objects with a consistent structure.

{
    "code": "string",
    "message": "string",
    "details": "string"
}

Error Codes

Code	HTTP Status Code	Description
INVALID_ARGUMENT	400	Client specified an invalid argument.
NOT_FOUND	404	The requested resource was not found.
ALREADY_EXISTS	409	The resource already exists.
PERMISSION_DENIED	403	The caller does not have permission to execute.
RESOURCE_EXHAUSTED	429	Resource has been exhausted (e.g., rate limit).
INTERNAL	500	Internal server error.
UNIMPLEMENTED	501	Method not implemented.
UNAVAILABLE	503	Service is currently unavailable.
UNAUTHENTICATED	401	Request does not have valid authentication.

Custom Errors

Custom errors provide specific information about error conditions and extend the standard error structure.

REST Custom Error Example

{
  "code": "INVALID_ARGUMENT",
  "message": "Invalid machine ID",
  "details": "Invalid machine ID: invalid UUID format"
}