Goa-gel-fullstack/Documentation/developers/errors.md

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error message",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ],
    "requestId": "req_abc123"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Validation Error
429	Rate Limited
500	Internal Error

Error Codes

Authentication Errors

Code	Description
AUTH_INVALID_TOKEN	Token is invalid or malformed
AUTH_EXPIRED_TOKEN	Token has expired
AUTH_MISSING_TOKEN	No token provided
AUTH_INSUFFICIENT_SCOPE	Token lacks required permissions

Validation Errors

Code	Description
VALIDATION_ERROR	Input validation failed
VALIDATION_REQUIRED	Required field missing
VALIDATION_FORMAT	Invalid field format
VALIDATION_RANGE	Value out of allowed range

Resource Errors

Code	Description
RESOURCE_NOT_FOUND	Requested resource doesn't exist
RESOURCE_CONFLICT	Resource state conflict
RESOURCE_LOCKED	Resource is locked

Business Logic Errors

Code	Description
APPLICATION_INVALID_STATE	Action not allowed in current state
DOCUMENT_TYPE_MISMATCH	Wrong document type
WORKFLOW_ERROR	Workflow processing error

Handling Errors

try {
  const result = await client.applications.create(data);
} catch (error) {
  if (error.code === 'VALIDATION_ERROR') {
    // Handle validation errors
    error.details.forEach(d => console.log(`${d.field}: ${d.message}`));
  } else if (error.code === 'AUTH_EXPIRED_TOKEN') {
    // Refresh token and retry
    await client.refreshToken();
    return retry();
  } else {
    // Log and report
    console.error('Unexpected error:', error.requestId);
  }
}