{
  "tag": {
    "name": "tags/01HX2ABC3DEF4GHI5JKL6MNO7P",
    "id": "01HX2ABC3DEF4GHI5JKL6MNO7P",
    "tag_name": "staging",
    "color": "#f59e0b",
    "create_time": "2025-10-14T12:00:00Z",
    "created_by": "engineer@example.com"
  }
}

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid request body",
    "details": [
      {
        "field": "color",
        "description": "color must be a hex string like '#RRGGBB' or '#RRGGBBAA'; got 'blue'"
      }
    ]
  }
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Authentication failed",
    "details": [
      {
        "field": "X-API-Key",
        "description": "Invalid or missing API key"
      }
    ]
  }
}

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions",
    "details": [
      {
        "field": "permissions",
        "description": "API key does not have required permission: tags:write"
      }
    ]
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Tag not found",
    "details": [
      {
        "field": "tag_id",
        "description": "Tag not found or not accessible by your organization"
      }
    ]
  }
}

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "Tag already exists",
    "details": [
      {
        "field": "tag_name",
        "description": "An active tag named 'production' already exists in your organization"
      }
    ]
  }
}

{
  "error": {
    "code": "INTERNAL",
    "message": "Internal server error",
    "details": [
      {
        "description": "An unexpected error occurred"
      }
    ]
  }
}